Skip to main content
The DELETE /tokens/:id endpoint revokes a token, preventing it from authenticating any future requests. Revocation takes effect immediately — any in-flight requests using the token may still complete, but all subsequent attempts will be rejected. After revocation, the token record remains in your workspace and is still retrievable via GET /tokens/:id, but its status changes to revoked. Required scope: tokens:revoke
Revocation is permanent and immediate. There is no way to reactivate a revoked token. If you need to restore access, you must create a new token and distribute the new secret to any services that relied on the revoked one.

​
Path parameters

​
id
string
required
The unique identifier of the token to revoke. Format: tok_a1b2c3d4e5f6g7h8i9j0k1l2. This is the id field returned when the token was created or listed.

​
Request

curl --request DELETE \
  --url https://api.tooken.io/v1/tokens/tok_a1b2c3d4e5f6g7h8i9j0k1l2 \
  --header "Authorization: Bearer tok_live_xxxxxxxxxxxxxxxxxxxx"

​
Response

A successful revocation returns 204 No Content with an empty body. There is no JSON payload to parse.

​
After revocation

Once revoked, the token’s record remains accessible via GET /tokens/:id. The response will show the token with "status": "revoked": 
{
  "id": "tok_a1b2c3d4e5f6g7h8i9j0k1l2",
  "name": "CI Deploy Token",
  "scopes": ["tokens:read", "tokens:write"],
  "status": "revoked",
  "created_at": "2026-01-15T09:00:00Z",
  "expires_at": "2027-01-15T09:00:00Z",
  "last_used_at": "2026-04-27T14:32:00Z",
  "created_by": "alice@example.com"
}
The token also appears in audit logs with a revoked event, showing who performed the revocation and when.

​
Error responses

If the token ID does not exist in your workspace, the API returns 404 Not Found: 
{
  "error": "not_found",
  "message": "Token tok_a1b2c3d4e5f6g7h8i9j0k1l2 not found",
  "status": 404
}
If you receive a 404 when attempting to revoke a token, the token is already absent from your workspace — either it was previously revoked or it never existed. Your integration can safely treat a 404 on a DELETE request as a successful outcome.