Token revocation

JWTs identify a credential with unique_id. Refresh and access tokens for that credential keep the same ID. A newly generated credential receives a distinct ID and inherits its issuer's signed token_ancestor IDs.

exp controls when a JWT stops authenticating requests. token_valid_until is the delegation and revocation-retention limit for its credential chain. Login sessions have an unbounded delegation limit, so a session that expires tomorrow can issue a personal access token expiring in one year, or a token without an expiration. The session JWT still expires at its configured time.

Issued API credentials use their requested expiry as their own fixed limit. An agent's refresh and access tokens retain that limit; refresh cannot extend it. Revoke an ID to block it and every descendant that carries it in its ancestry.

Request metrics in logship.backend.security.token.usage include TokenId, TokenRootId, TokenParentId when present, and TokenValidUntil as Unix seconds. User and agent credentials both emit these fields.

Administration

• Account Settings → API Tokens → Token Revocations: account administrators can revoke access within that account.
• System Administration → Token Revocations: global administrators can revoke an ID across all accounts and inspect all active revocations.

Enter the token ID and its revocation-retention limit, or paste a JWT to read those fields locally. The JWT is not sent or stored. Use token_valid_until, or exp for older tokens. Select Retain revocation indefinitely for an unbounded limit. This can apply to an expiring login session because credentials issued by that session can outlive its JWT.

Only revoked IDs are persisted. API hosts fetch the list every 30 seconds and check each request's ID and ancestors against an in-memory snapshot. Account revocations apply to requests routed to that account; global revocations apply everywhere. If a host cannot obtain a snapshot, or its snapshot is over 60 seconds old, it rejects authenticated requests until it can refresh the list.

The database service runs a separate cleanup job every minute to delete expired revocations. Listing revocations is read-only. Revoking an existing ID can extend its retention time, but cannot shorten it.

API

{
  "tokenId": "ae0ce680-4ed6-494f-acda-6f76d61d28c9",
  "validUntil": "2027-01-01T00:00:00Z"
}

The account endpoints require account-administrator access. System listing and revoking other IDs globally require global-administrator access. An authenticated user can also revoke their current ID globally; its retention time is at least the signed validity limit.

Existing credentials

Existing unique_id values remain valid. Tokens without an ID receive a stable local ID derived from the already authenticated JWT. Older tokens use their signed exp as the validity limit. Previously issued tokens cannot acquire ancestry retroactively; new descendants carry ancestry when they are issued.

Sign in again after upgrading to obtain a session with the corrected delegation limit. Requests exceeding a bounded issuer's limit return an error instead of silently issuing a shorter-lived PAT. Already issued tokens keep their signed expiry; reissue any token whose expiry was previously shortened.