API keys

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 model behind keys, how one binds to an organization and scopes every request, see Organizations and tenancy.

API key format

Production keys start with samva_sk_live_; keys minted outside production start with samva_sk_test_. Each key authenticates requests for the organization it belongs to.

Using API keys

Include the key in the X-API-Key header on every request.

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>"
    }
  }'

Key handling

Key lifecycle

Keys are created and managed under Developers → API Keys in the Samva Dashboard. Each key carries a set of permissions and an optional expiry, both set at creation. The full key value is returned only at creation time and is not retrievable afterward; a lost key must be replaced. Keys can be revoked at any time, and a revoked key stops authenticating immediately.

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.

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 without the scope the endpoint requires.

{
  "_tag": "ForbiddenError",
  "message": "API key lacks the required permission"
}

These are the authentication-specific errors. For the full list the API can return, with each error's fields and how to resolve it, see the Error reference.

Related