Create an API key
Create a new API key for your organization. The secret (am_live_...) is
returned only once, in the plaintext field. Store it securely,
because only a hash is kept and a lost key cannot be recovered (rotate to
get a new one).
The scopes you request must be a subset of the scopes your own
credentials already hold; requesting more returns 403 FORBIDDEN. Unknown,
empty, or duplicate scopes return 400 INVALID_INPUT.
Requires the apikeys:write scope. Key creation is rate limited to 10 per
minute (shared with key rotation); bursts return 429 RATE_LIMITED with a
Retry-After header.
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/api-keys" \ -H "Content-Type: application/json" \ -d '{ "label": "order-confirmations bot", "scopes": [ "messages:send" ] }'{
"id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b4",
"org_id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b5",
"label": "order-confirmations bot",
"prefix": "am_live_oc01",
"scopes": [
"messages:send"
],
"created_at": "2026-04-26T12:00:00Z",
"last_used_at": null,
"revoked_at": null,
"plaintext": "am_live_oc01abcdefghijklmnopqrstuvwxyz0123"
}{
"success": false,
"error": {
"code": "INVALID_INPUT",
"message": "api key: unknown scope \"messages:write\": UNKNOWN_SCOPE: invalid input",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "rate limited",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}