API keys

API reference descriptions are provided in English to preserve the exact published contract.

List API key metadata

GET /v1/accounts/{AC}/api-keys

getV1AccountsByAcApiKeysPaginated200

List API keys: name, scopes, restrictions and last use. Secrets are never shown. Required scope: `api_keys:read`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Create an API key and reveal its secret once

POST /v1/accounts/{AC}/api-keys

postV1AccountsByAcApiKeysIdempotency-Key required201

Create an API key. The secret is in this response only; store it now. Give each key the fewest scopes it needs. Required scope: `api_keys:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (7 fields)

Request body
Name	Type	Required
`allowedCidrs`	string (max 64 chars)[]
`displayName`	string (max 128 chars)	yes
`expiresAt`	string (date-time)
`requireSigning`	boolean
`scopes`	string (pattern ^(?:[]\|[a-z][a-z0-9_-]:[a-z][a-z0-9_-]*)$)[]	yes
`stepUpToken`	string (max 256 chars)	yes
`subaccountSid`	string (SA… SID)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List the scopes an API key can be given

GET /v1/accounts/{AC}/api-keys/scopes

getV1AccountsByAcApiKeysScopes200

The scope catalogue, grouped, with plain-language labels (M-38). `held` marks the scopes the caller may put on a new key: a key never exceeds the user or key creating it. Required scope: `api_keys:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Get API key metadata

GET /v1/accounts/{AC}/api-keys/{SK}

getV1AccountsByAcApiKeysBySk200

Required scope: `api_keys:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`SK`	path · string (SK… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Update API key restrictions

PATCH /v1/accounts/{AC}/api-keys/{SK}

patchV1AccountsByAcApiKeysBySkIdempotency-Key required200

Required scope: `api_keys:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`SK`	path · string (SK… SID)	yes

Request body (5 fields)

Request body
Name	Type	Required	Description
`allowedCidrs`	string (max 64 chars)[]
`displayName`	string (max 128 chars)
`expiresAt`	string (date-time) \| null
`requireSigning`	boolean
`stepUpToken`	string (max 256 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Disable an API key

POST /v1/accounts/{AC}/api-keys/{SK}/disable

postV1AccountsByAcApiKeysBySkDisableIdempotency-Key required200

Required scope: `api_keys:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`SK`	path · string (SK… SID)	yes

Request body (2 fields)

Request body
Name	Type	Required	Description
`reason`	string (max 1000 chars)	yes
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Stop the replaced secret of a rotated API key working now

POST /v1/accounts/{AC}/api-keys/{SK}/end-overlap

postV1AccountsByAcApiKeysBySkEndOverlapIdempotency-Key required200

After a rotation the previous secret keeps working until previousSecretExpiresAt. Call this once every client uses the new secret. It only narrows access, so it needs no step-up. Required scope: `api_keys:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`SK`	path · string (SK… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`reason`	string (max 1000 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Revoke an API key

POST /v1/accounts/{AC}/api-keys/{SK}/revoke

postV1AccountsByAcApiKeysBySkRevokeIdempotency-Key required200

Revoke a key immediately and for good. A revoked key is never re-enabled. Required scope: `api_keys:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`SK`	path · string (SK… SID)	yes

Request body (2 fields)

Request body
Name	Type	Required	Description
`reason`	string (max 1000 chars)	yes
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Rotate an API key and reveal the replacement secret once

POST /v1/accounts/{AC}/api-keys/{SK}/rotate

postV1AccountsByAcApiKeysBySkRotateIdempotency-Key required200

Replace a key's secret. The response shows the new secret once; store it now. Required scope: `api_keys:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`SK`	path · string (SK… SID)	yes

Request body (3 fields)

Request body
Name	Type	Required	Description
`overlapHours`	integer (0–168)		Hours the current secret stays valid beside the new one. Default 24; 0 ends it immediately; at most 168 (7 days).
`reason`	string (max 1000 chars)	yes
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.