API keys

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

GETList API key metadataapiKeys.list
POSTCreate an API key and reveal its secret onceapiKeys.create
GETList the scopes an API key can be givenapiKeys.scopes.list
GETGet API key metadataapiKeys.retrieve
PATCHUpdate API key restrictionsapiKeys.update
POSTDisable an API keyapiKeys.disable
POSTStop the replaced secret of a rotated API key working nowapiKeys.endOverlap
POSTRevoke an API keyapiKeys.revoke
POSTRotate an API key and reveal the replacement secret onceapiKeys.rotate

List API key metadata

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

apiKeys.listSDK operation getV1AccountsByAcApiKeys

List API keys: name, scopes, restrictions and last use. Secrets are never shown.

Required scope: api_keys:read.Paginated

Parameters

limitinteger (1–100)query
cursorstring (max 2048 chars)query

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

curl "https://api.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/api-keys" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21"

Responses

Create an API key and reveal its secret once

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

apiKeys.createSDK operation postV1AccountsByAcApiKeys

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.Idempotency-Key required

Request body

displayNamestring (max 128 chars)Required
scopesstring (pattern ^(?:[*]|[a-z][a-z0-9_-]*:[a-z*][a-z0-9_*-]*)$)[]Required
stepUpTokenstring (max 256 chars)Required
allowedCidrsstring (max 64 chars)[]
expiresAtstring (date-time)
requireSigningboolean
subaccountSidstring (SA… SID)

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

curl -X POST "https://api.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/api-keys" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "displayName": "string",
  "scopes": [],
  "stepUpToken": "string"
}'

Responses

List the scopes an API key can be given

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

apiKeys.scopes.listSDK operation getV1AccountsByAcApiKeysScopes

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.

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

curl "https://api.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/api-keys/scopes" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21"

Responses

Get API key metadata

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

apiKeys.retrieveSDK operation getV1AccountsByAcApiKeysBySk

Required scope: api_keys:read.

Parameters

SKstring (SK… SID)Required

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

curl "https://api.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/api-keys/SK..." \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21"

Responses

Update API key restrictions

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

apiKeys.updateSDK operation patchV1AccountsByAcApiKeysBySk

Required scope: api_keys:write.Idempotency-Key required

Parameters

SKstring (SK… SID)Required

Request body

allowedCidrsstring (max 64 chars)[]
displayNamestring (max 128 chars)
expiresAtstring (date-time) | null
requireSigningboolean
scopesstring (pattern ^(?:[*]|[a-z][a-z0-9_-]*:[a-z*][a-z0-9_*-]*)$)[]
stepUpTokenstring (max 256 chars)

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

curl -X PATCH "https://api.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/api-keys/SK..." \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)"

Responses

Disable an API key

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

apiKeys.disableSDK operation postV1AccountsByAcApiKeysBySkDisable

Required scope: api_keys:write.Idempotency-Key required

Parameters

SKstring (SK… SID)Required

Request body

reasonstring (max 1000 chars)Required
stepUpTokenstring (max 256 chars)Required

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

curl -X POST "https://api.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/api-keys/SK.../disable" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string",
  "stepUpToken": "string"
}'

Responses

Stop the replaced secret of a rotated API key working now

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

apiKeys.endOverlapSDK operation postV1AccountsByAcApiKeysBySkEndOverlap

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.Idempotency-Key required

Parameters

SKstring (SK… SID)Required

Request body

reasonstring (max 1000 chars)Required

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

curl -X POST "https://api.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/api-keys/SK.../end-overlap" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string"
}'

Responses

Revoke an API key

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

apiKeys.revokeSDK operation postV1AccountsByAcApiKeysBySkRevoke

Revoke a key immediately and for good. A revoked key is never re-enabled.

Required scope: api_keys:write.Idempotency-Key required

Parameters

SKstring (SK… SID)Required

Request body

reasonstring (max 1000 chars)Required
stepUpTokenstring (max 256 chars)Required

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

curl -X POST "https://api.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/api-keys/SK.../revoke" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string",
  "stepUpToken": "string"
}'

Responses

Rotate an API key and reveal the replacement secret once

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

apiKeys.rotateSDK operation postV1AccountsByAcApiKeysBySkRotate

Replace a key's secret. The response shows the new secret once; store it now.

Required scope: api_keys:write.Idempotency-Key required

Parameters

SKstring (SK… SID)Required

Request body

reasonstring (max 1000 chars)Required
stepUpTokenstring (max 256 chars)Required
overlapHoursinteger (0–168)
Hours the current secret stays valid beside the new one. Default 24; 0 ends it immediately; at most 168 (7 days).

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

curl -X POST "https://api.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/api-keys/SK.../rotate" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string",
  "stepUpToken": "string"
}'

Responses