Documentation menu

Personal access tokens API#

PAT management requires apps:manage. A caller can mint only scopes allowed by both its own scope set and the current organization role.

List tokens#

GET/pats

Returns metadata such as id, name, scopes, creator, creation time, optional expiry, and revocation state. Secrets are never returned by list or fetch operations.

Create a token#

POST/pats

Send a name, requested scopes, and optional expiry. The response returns 201, a Location header, and the pat_... secret exactly once.

json

{
  "name": "skycrane reporting",
  "scopes": ["query:read", "data:read"]
}

Store the secret immediately. Supernova stores its hash and cannot recover the original. Invalid bodies return 400 invalid_pat_parameters with a named param when possible.

Revoke a token#

DELETE/pats/{id}

Revocation prevents the PAT from authenticating future requests. It does not cancel a query or send already accepted under that principal; use the relevant resource endpoint for active work.

A token id outside the caller's organization is indistinguishable from an unknown id. Rotate a credential by creating the replacement, updating clients, verifying GET /whoami, then revoking the old PAT.