Authentication

How to authenticate requests to the Send API

Every request to the Send API is authenticated with an API key. Keys are created and revoked in the dashboard; there is no API for managing them.

Sending the key

Put the key in the Authorization header as a bearer token:

curl https://api.do.dev/v1/send/emails \
  -H "Authorization: Bearer do_live_..."

The X-API-Key header is also accepted and behaves identically:

curl https://api.do.dev/v1/send/emails \
  -H "X-API-Key: do_live_..."

If both are present, Authorization wins.

Key formats

Prefix	Notes
`do_live_`	Current keys, created in the dashboard.
`sk_live_`	Legacy keys issued before the do.dev platform migration. They still send email; rotate to a `do_live_` key when convenient. They cannot manage webhooks, which need a `do_live_` key.

There is no test mode. Every key sends real email. To test an integration without reaching real inboxes, send to an address on a domain you control, or use the Amazon SES mailbox simulator addresses such as success@simulator.amazonses.com and bounce@simulator.amazonses.com. Simulator traffic does not count against your reputation.

Scopes

Keys carry scopes. Send endpoints that create or change data (sending, adding domains, creating templates, unsuppressing) require send:write; read endpoints require send:read. Keys created in the send.dev dashboard have both. A request with a key that lacks the required scope receives 403 with code forbidden.

Failure responses

Status	Code	When
`401`	`unauthorized`	Header missing, key unknown, key revoked, or key expired.
`403`	`forbidden`	Key is valid but lacks the scope, or is not enabled for the Send service.
`429`	`rate_limited`	Too many requests for this key. See Rate limits.

All errors share the envelope described in Errors:

{
  "error": {
    "code": "unauthorized",
    "message": "API key required. Use Authorization: Bearer <key> or X-API-Key header."
  }
}

Keeping keys safe

Call the API from your server only. A key in browser or mobile code is public.
Load keys from environment variables or a secrets manager, not from source control.
Create one key per deployment or service so you can revoke a single key without an outage.
If a key is exposed, revoke it in the dashboard immediately. Revocation takes effect within a minute; requests using the old key fail with 401.

See API Keys for how to create, name, and revoke keys.