Revoke a token

A token is a short-lived session credential issued for a principal after successful authentication. Use it in place of an API key for the duration of the session, then revoke it when it is no longer needed.

Revoke a session token previously issued for the specified principal. Authenticate the request with an API key in x-api-key, and send the token to revoke in the required query parameter. A successful DELETE /v1/token returns 204 No Content, so do not attempt to parse a response body. To issue a replacement token, see Sign in.

A 404 means the token was not found for that principal; verify that both values correspond to the original sign-in response. For 401, 403, or 400, check the API key, caller permissions, and required query parameters respectively.

Keep the token out of logs

This endpoint carries the token in the query string.

Redact the request URL from access logs, traces, error reports, and command history. Never print or log the token while troubleshooting.

DELETE

{{host}}/v1/token?principal={{principal}}&token={{token}}

VERB:DELETE

BASE URL:{{host}}/v1/token

QUERY STRING:?principal={{principal}}&token={{token}}

Query parameters#

RequiredOptional

principalstring
Required
Principal identifier to sign in as (e.g. owner or logical principal id).
example: root
tokenstring
Required
The token string returned by `POST /v1/token` to revoke.
example: 1ZOUMYM1rLWKuWWkcekZwa8TJbaNbLw2

Headers#

RequiredOptional

Send these headers with the request. Names are case-insensitive per HTTP rules.

x-api-keyRequired
Your BigState API key.
{{apiKey}}
Content-TypeRequired
MIME type of the request body.
application/json
AcceptRequired
MIME types the client can understand in the response.
application/json

Need a session token? See Token sign in.

Response parameters#

204Response body · no content
The token was revoked. No response body.
401
Unauthorized.
403
Access denied. The caller does not have sufficient rights to perform this operation.
404
No such token for this principal.
400Response body · object
Bad request.
```
{
  "error": 6,
  "desc": "Invalid request"
}
```
- errornumber
  Numeric error code. Use the response `desc` field for the human-readable explanation.
- descstring
  Human-readable description of the error.

Examples#

Revoke a token

Delete a session token for the principal. Success: 204, no body.


curl https://api.bigstate.dev/v1/token?principal=root&token=1ZOUMYM1rLWKuWWkcekZwa8TJbaNbLw2 \
  --request DELETE \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json'

Description
Query parameters
Headers
Response parameters
Examples