Revoke one agent token, or every live token of an account

POST /api/v1/agent-tokens/revoke · operationId revokeAgentTokens

For developers: your server sends this request with a server key; it is not a button in the dashboard.

Send exactly one of token (the token itself), tokenId (from the issue response) or accountId (every live token of that account). An empty body, or two of them, is 400 bad_request: nothing is ever revoked by default. Idempotent: revoking a revoked token again answers revoked 0.

#Authentication

Send Authorization: Bearer YOUR_SERVER_KEY (siteServerKey: Site server key in Authorization: Bearer <key> (the scheme is case-insensitive and required; a bare key is 401). Shown once on creation or rotation. Publishable keys cannot authenticate). Keep the server key in server-only configuration; never send it to a browser.

#Request body

Content-Type: application/json (required)

Exactly one of token, tokenId or accountId.

• token (string, optional)
• tokenId (string, optional)
• accountId (string, optional) · maxLength 512

{
  "tokenId": "atok_PASTE_TOKEN_ID"
}

#Responses

• 200: Success · body object
• 400: bad_request: the request is invalid; message says what to fix and field names the request field · body Error
• 401: unauthorized (missing or invalid server key, missing Bearer scheme) · body Error
• 403: forbidden: the call came from a browser page or another Site; call from your server with this Site’s server key · body Error
• 404: not_found: unknown path, or an ID in the path that is not on this Site · body Error
• 409: conflict: the request contradicts what is already recorded; message says what · body Error
• 413: payload_too_large: the request body exceeds 131072 bytes · body Error
• 429: rate_limited: wait for Retry-After · body Error · headers Retry-After
• 500: internal_error: fail the protected action; do not retry automatically · body Error
• 503: service_unavailable: temporarily unavailable; only verify retries · body Error

#Success body fields

• revoked (integer, required) · minimum 0: How many live tokens this call revoked.

Failures are not verdicts. Error bodies follow the Error schema: code is one of bad_request, unauthorized, session_reinit_required, forbidden, not_found, conflict, identity_required, payload_too_large, rate_limited, internal_error, service_unavailable, request_failed, approval_invalid, approval_used, approval_expired, approval_mismatch, step_up_not_held, step_up_mismatch, step_up_settled, step_up_expired, step_up_superseded, agent_tokens_disabled, tool_not_approved, tool_not_read_only. Errors and retries explains each code and what to do.

#Example

curl -sS -X POST 'https://app.trytelltale.dev/api/v1/agent-tokens/revoke' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"tokenId":"atok_PASTE_TOKEN_ID"}'

const response = await fetch("https://app.trytelltale.dev/api/v1/agent-tokens/revoke", {
  method: "POST",
  headers: {
    Authorization: 'Bearer ' + process.env.TELLTALE_SERVER_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "tokenId": "atok_PASTE_TOKEN_ID"
  }),
  signal: AbortSignal.timeout(5000)
});
const result = await response.json();

Machine-readable contract: openapi.json. Request builder: the API explorer shows every operation as curl; it sends requests only on a local dashboard.