Token API Specification Reference
The Token API provides HTTP methods for managing access tokens and permissions for the database.
The API is available only when the RS_API_TOKEN environment variable is set.
Get a List of Tokens
This method returns a list of tokens and their metadata (it never returns token values). To use it, you need an access token with full access.
Show Information about a Token
This method provides full information about a token except its secret value. The method requires an access token with full access.
Create a New Token
The method creates a new access token from a JSON request body. The request can include permissions and additional token settings such as expiration, inactivity TTL, and an IP allowlist. To use this method, you need an access token with full access.
Token Fields and Behavior
Token read endpoints (GET /api/v1/tokens, GET /api/v1/tokens/:token_name, GET /api/v1/me) return additional fields:
created_at: Timestamp when the current token value was issued (created or rotated).expires_at: Absolute expiration time. After this time, the token is unusable.ip_allowlist: If non-empty, requests using this token are accepted only from the listed client IPs or CIDRs.last_access: Timestamp of the most recent token usage, ornullif the token has not been used yet. This value is derived from audit metadata (see Audit Log) and may remainnullif auditing is disabled.ttl: Inactivity timeout (seconds). When set, the server can expire tokens that have not been used within the TTL.is_expired: Server-computed indicator showing whether the token is currently expired (for example due toexpires_atorttl).
Rotate a Token
This method rotates a token value (secret) in one explicit API call. The old value is invalidated immediately after rotation. To use it, a client should have an access token with full access.
Remove a Token
This method removes or revokes a token. To use it, a client should have an access token with full access.
Get Full Information about Current API Token
This method takes a token from the Authentication header and returns its name, permissions, and additional information.