Skip to main content
POST
/
v1
/
api-keys
Create API key
curl --request POST \
  --url https://api.example.com/v1/api-keys \
  --header 'Content-Type: application/json' \
  --data '
{
  "label": "<string>"
}
'
{
  "keyId": "<string>",
  "prefix": "<string>",
  "secret": "<string>",
  "label": "<string>",
  "createdAt": {}
}
This endpoint requires a Cognito JWT from the dashboard. API-key bearer tokens are refused (403) by design — a leaked key can’t entrench itself by creating more keys.Most customers use the dashboard’s Settings → API Keys UI, not this endpoint directly. Documented here for automation / admin scripts that already have a Cognito session.

​
Request body

​
label
string
Optional human-readable name. Shows up in the dashboard listing and in lastUsedAt audits. Max 60 chars.

​
Response — 201 Created

​
keyId
string
Opaque identifier for this key. Same value as prefix — used to reference the key on DELETE.
​
prefix
string
The first 16 characters of the secret (e.g. sb_live_abcd1234). Safe to display; used as the key’s public identifier.
​
secret
string
The full secret, returned exactly once. Save it immediately — the server stores only a hash, so it can’t be recovered.
​
label
string
The label you supplied (or null).
​
createdAt
string (ISO 8601)

​
Example

curl "$API_BASE/api-keys" -X POST \
  -H "Authorization: Bearer $COGNITO_JWT" \
  -H "Content-Type: application/json" \
  -d '{"label": "production"}'
Response (201)
{
  "keyId": "sb_live_Pq778jCf",
  "prefix": "sb_live_Pq778jCf",
  "secret": "sb_live_Pq778jCf_d1Iov4oX4MpVDhBNqxKJEXVFbJRDkHHkT6AyklZc",
  "label": "production",
  "createdAt": "2026-04-21T..."
}

​
Errors

CodeMeaning
401Missing Authorization header, or JWT expired / invalid
403Used an API key instead of a Cognito JWT
400Invalid JSON body