Authentication

Bearer API keys

Authenticate every /api/v1 request with an API key in the Authorization header. Keys start with tp_live_; the header must be exactly Bearer tp_live_….

Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxx

Create keys in Dashboard → API Keys or with POST /v1/api-keys. The full key is shown only once; Bytesms stores a hash, and the dashboard shows only the prefix. A key always acts on the workspace it was created in.

A missing, malformed, unknown or expired key is rejected with 401:

{
  "statusCode": 401,
  "message": "Invalid API key",
  "name": "unauthorized"
}

Permissions

A sending_access key calling any other endpoint gets 401 restricted_api_key:

{
  "statusCode": 401,
  "message": "This API key is restricted to only send emails.",
  "name": "restricted_api_key"
}

Domain-scoped keys

A sending_access key can additionally be restricted to one domain (domain_id when creating it). It may then only send from addresses on that domain; anything else is 403 restricted_api_key. A key created with a domain_id and no permission defaults to sending_access; full_access together with a domain is refused. If the domain is later deleted, the key stops working for sending (fail-closed) — create a new one.

Suspended keys

A key can be suspended by the Bytesms team (for example after abuse reports). Every request with it is refused with 403 suspended_api_key and a reason in message.

Other surfaces

• SMTP — username bytesms, password = an API key (its permission and domain scope apply).
• MCP server — an API key as Bearer token, or OAuth 2.1 (scopes full / sending).