Authentication

The Sent API v3 authenticates every request with an API key. Send it in the x-api-key header, or as a Bearer token in the Authorization header. The key identifies your account, and no other identifier is required.

Request headers

Header	Type	Required	Description
`x-api-key`	String (UUID)	Either	Your secret API key. Identifies and authorizes your account on every request.
`Authorization`	`Bearer <api key>`	Either	The same API key as a Bearer token, for clients that can only send OAuth2 or Bearer credentials.

Send one header or the other. If a request carries both, the API uses x-api-key and ignores Authorization. The Bearer scheme name is case-insensitive. Any other scheme, such as Basic, counts as a missing key.

API keys are UUIDs (for example, xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). There is one key format for all environments.

Sandbox behavior is controlled per request with the "sandbox" body field on mutation endpoints, not by a separate key type. See Sandbox mode.

To create, rotate, or revoke keys, see Creating and managing API keys.

Example requests

curl https://api.sent.dm/v3/me \
  -H "x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

The same request with the key as a Bearer token:

curl https://api.sent.dm/v3/me \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Response headers

All v3 responses include:

Header	Description
`X-Request-Id`	Unique request identifier for tracing and support, in the form `req_` followed by 16 hex characters. If the request supplies an `X-Request-Id` header, that value is echoed back.
`X-Response-Time`	Server processing time in milliseconds, for example `12ms`.
`X-API-Version`	Always `v3`.

Authentication errors

Authentication failures return the standard v3 error envelope:

{
  "success": false,
  "status": 401,
  "error": {
    "code": "AUTH_002",
    "message": "Invalid or missing API key",
    "doc_url": "https://docs.sent.dm/reference/api/authentication"
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f60718",
    "timestamp": "2026-07-25T12:00:00+00:00",
    "version": "v3"
  }
}

AUTH error codes

Code	Status	Message	Returned when
`AUTH_001`	401	Authentication required	The request has no authenticated identity for a reason other than the API key, for example an invalid or expired voice token. A missing or unrecognized API key is `AUTH_002`.
`AUTH_002`	401	Invalid or missing API key	Neither header carries a key, the key is empty, or it does not match an active key.
`AUTH_003`	401	Missing or invalid sender identifier	Legacy v1/v2 endpoints only: the `x-sender-id` header is missing or is not a valid UUID. v3 endpoints do not return this code.
`AUTH_004`	403	Access denied	The authenticated account does not have permission for the operation. See Roles and permissions.
`AUTH_005`	403	Account onboarding is not complete	Defined for onboarding gating; not returned by v3 authentication.
`AUTH_006`	403	KYC verification is not complete	Defined for onboarding gating; not returned by v3 authentication.
`AUTH_007`	403	Channel setup is not complete	Defined for onboarding gating; not returned by v3 authentication.

Onboarding state does not block authentication. Message volume during partial onboarding is limited in the send pipeline instead: over-limit messages are accepted by the API and finalized with a BLOCKED status. See Trust & Safety.

The complete list of API error codes is in the Error catalog.

Failed-attempt lockout

After 10 consecutive failed authentication attempts with the same credential, the API locks that credential and returns 429 with error code BUSINESS_002, the message Too many failed authentication attempts. Please try again later., and a Retry-After: 60 header. The lockout duration escalates with continued failures: 1, 5, 15, 30, then 60 minutes. A successful authentication resets the counter.

Rate limits

Authenticated requests are rate limited per customer account. For limits, tiers, and 429 response headers, see Rate limits.

Creating and managing API keys: create, store, verify, rotate, and revoke keys.
API authentication: why v3 authenticates with a single header-based key.
Error catalog: every error code across the API.

On this page