API keys

Every API request is authenticated with an API key sent as a bearer token:

HTTP

Authorization: Bearer us_123456789

Keys belong to one organization. Every request made with a key acts on that organization's data.

Create a key

Create keys in the dashboard under API Keys, or with POST /api-keys. The full token is returned once, when the key is created. usend stores only a hash of it, so copy it to a secret store right away. Lists show only the first characters of the token (token_prefix).

Tokens start with us_.

Permissions

Permission	Can call
`full_access`	Every endpoint in the API reference. This is the default.
`sending_access`	Only `POST /emails` and `POST /emails/batch`.

A sending_access key can also be limited to one domain (domain_id). It can then only send from addresses on that domain (or its subdomains); anything else fails with 403 restricted_api_key. Only sending_access keys can be restricted to a domain.

Calling any other endpoint with a sending_access key fails with:

JSON

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

Tip

Give each application or environment its own sending_access key. If one leaks, delete it without affecting the others.

Authentication errors

Status	Name	When
401	`missing_api_key`	The `Authorization` header is missing or is not `Bearer <token>`.
403	`invalid_api_key`	The key does not exist or was deleted.
401	`restricted_api_key`	A `sending_access` key called an endpoint other than sending.
403	`restricted_api_key`	A domain-restricted key sent from a different domain.

Rotate or revoke a key

Create the new key, deploy it, then delete the old one in the dashboard or with DELETE /api-keys/{id}. Deletion takes effect immediately. The dashboard and GET /api-keys show when each key was last used (last_used_at), which helps you find unused keys.

Each key has its own rate limit.

#Create a key

#Permissions

#Authentication errors

#Rotate or revoke a key

Create a key

Permissions

Authentication errors

Rotate or revoke a key