Skip to main content
The JWT session module issues short-lived access tokens (JWTs) and long-lived refresh tokens. Access tokens are stateless (no DB lookup on every request). Refresh tokens are opaque random strings stored hashed in the database and rotate on every use. It is a module you create yourself with createJwtSessionModule. There is no jwtSession() plugin, no theauth.jwt property, and no /auth/jwt/* routes. You call the module from your own handlers.

Setup

Usage

Every method returns a Result: { success: true, data } or { success: false, error: { code, message } }. They do not throw for normal failures.

Create a session

Custom claims come from the customClaims function in the config, which receives { id, email?, name? }. createSession does not take a claims argument.

Verify an access token

Verification does not touch the database. It fails on a bad signature, expiry, or issuer or audience mismatch (error codes include TOKEN_EXPIRED, INVALID_TOKEN, ISSUER_MISMATCH, AUDIENCE_MISMATCH).

Refresh

A refresh issues a new pair for the same user ID. The new access token carries sub and your customClaims output, but not the email or name from the original createSession call. Errors are REFRESH_TOKEN_NOT_FOUND, REFRESH_TOKEN_USED, and REFRESH_TOKEN_EXPIRED. Presenting an already-used refresh token fails but does not revoke the user’s other refresh tokens.

Revoke

revokeSession marks one refresh token as used. Revoking an already-revoked or unknown token is a no-op. There is no revoke-all method on this module.

Algorithms

The module does not publish a JWKS endpoint. If other services verify your tokens with a public key, serve that key yourself.

HTTP endpoints

The module ships no HTTP handler. Expose the methods through routes you write, for example POST /auth/token calling createSession and POST /auth/refresh calling refreshSession.
Access tokens are stateless. Revocation only affects refresh tokens. For immediate access token invalidation, use short TTLs (5-15 minutes).
Set emitAgenticJwtClaims: true to add agent_id, agent_type, and trust_tier claims when createSession receives an agenticContext on the user. See Standards alignment.

Sessions

Cookie sessions, JWT tokens, and the full session lifecycle.

Cookie options

Cookie attributes for same-domain browser setups.

MCP OAuth 2.1

OAuth 2.1 token issuance for MCP tool server authorization.

Standards alignment

IETF draft claims added to agent JWTs.
Last modified on October 18, 2026