Skip to content
qibdo qibdo
Theme
Book a demo

Session tokens

IAM issues two kinds of credentials: opaque session tokens for users, and signed JWTs for service accounts. This page covers the session tokens.

A session token is an opaque credential for an authenticated user. This page explains the token lifecycle, what describes a token, and how tokens are referenced, refreshed, and revoked.

Two tokens, two jobs

Section titled “Two tokens, two jobs”

Authenticating returns a pair of tokens with distinct roles:

  • The access token is the bearer credential. Present it in the Authorization header on every authenticated request. It is short-lived: it expires soon after it is issued.
  • The refresh token (prefixed qbr_) is longer-lived. Its only job is to obtain a new access token, without sending the user’s password again.

Both tokens are opaque: clients treat them as bytes and never parse them.

The hash fingerprint

Section titled “The hash fingerprint”

The raw token value is returned only once, when you authenticate or refresh. After that, a token is referenced by its hash, a SHA-512 hex fingerprint of 128 lowercase hex characters.

The hash is both the natural identifier and the lookup key: it is the value you pass to revoke a token, and the value that appears when you list your tokens. So that clients never need to compute SHA-512 themselves, the authenticate and refresh responses also return the freshly minted access token’s fingerprint directly.

Because only the hash is stored and surfaced, leaking a token listing does not leak a usable credential.

Token metadata

Section titled “Token metadata”

Each token carries metadata captured at creation time and never modified afterwards (write-once): the client IP address, and the User-Agent value when the token was created. This is what lets a user audit their own active sessions (“which device, from which IP”) when listing their tokens.

Expiry and refresh

Section titled “Expiry and refresh”

A token has an expiry time, after which it can no longer authenticate. Rather than forcing re-authentication, a client exchanges a valid refresh token for a new pair:

  • Refreshing consumes the old refresh token and issues a new access + refresh pair. Rotation retires the whole session family, so the previous access token stops working immediately, and the consumed refresh token cannot be reused.
  • Refreshing does not require bearer authentication; the refresh token itself is the credential.

Revocation

Section titled “Revocation”

Revoking a token terminates a session immediately. It has two forms:

  • Self-revoke: revokes the bearer credential taken from the Authorization header. This is the common “log me out” case.
  • Targeted revoke: revokes a named session, identified by its hash. The caller must own that session, or hold platform-scoped iam.token.revoke.

Revocation cascades: revoking a token also revokes its sibling tokens in the same family. To avoid leaking which hashes exist, a revoke returns NOT_FOUND both when a hash does not exist and when the caller is not permitted to see it.

The resulting operation records why the session was revoked, so operators can distinguish the cases in the audit log: a self-revoke, a targeted revoke of the caller’s own session, an admin revoking another user’s session, or an automatic revoke from the per-user session soft-cap.

Section titled “Related”