Authentication
API key reference for the Samva email API — key format, the X-API-Key header, rate limiting, and authentication errors.
Samva authenticates email API requests with an API key sent in the X-API-Key header. This page documents key format, request authentication, rate limiting, and authentication errors. For the underlying model — how keys map to organizations and tenancy — see Authentication and tenancy.
API key format
Every Samva API key starts with the sk_sm_ prefix. There is no separate live and test key type — one key authenticates all requests for the organization it belongs to.
Using API keys
Include the key in the X-API-Key header on every request.
The SDK reads the key from the apiKey option and sets the header for you.
import { createClient } from "samva";
const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });curl -X POST https://api.samva.app/v1/messages \
-H "X-API-Key: $SAMVA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": [{ "email": "ada@example.com" }],
"channel": "email",
"email": {
"subject": "Welcome to Samva",
"html": "<h1>Welcome!</h1>"
}
}'Store keys in environment variables, never in source. The full key value is shown only once at creation time.
Key handling
| Practice | Detail |
|---|---|
| Use environment variables | Read the key from the environment; never hardcode it in source. |
| Scope permissions | Set the minimum permissions required when creating a key. |
| Rotate keys | Replace keys periodically and after any suspected exposure. |
| Monitor usage | Track per-key usage in the Samva Dashboard. |
Creating a key
- Open the Samva Dashboard.
- Go to Developers → API Keys.
- Click Create API Key, set permissions and an optional expiry.
- Copy the key immediately — it is not shown again.
Rate limiting
Send throughput is rate limited per organization. When a limit is exceeded, the request returns 429 Too Many Requests with a RateLimitedError body. The retryAfterSeconds field tells you how long to wait before retrying.
{
"_tag": "RateLimitedError",
"retryAfterSeconds": 30
}Back off for at least retryAfterSeconds seconds before sending the request again.
Authentication errors
Errors are returned as tagged JSON bodies. Each body carries a _tag identifying the error and a message describing it.
| Status | _tag | Description | Resolution |
|---|---|---|---|
401 | UnauthorizedError | Invalid or missing API key | Check the X-API-Key header value |
403 | ForbiddenError | Insufficient permissions | Use a key with the required scope |
Invalid or missing API key
Returned when the API key cannot be validated.
{
"_tag": "UnauthorizedError",
"message": "Invalid API key"
}Insufficient permissions
Returned when the key is valid but not authorized for the request — for example, a key not associated with an organization.
{
"_tag": "ForbiddenError",
"message": "API key is not associated with an organization"
}