Skip to main content

Stateless JWT access tokens

This document explains how to configure stateless JWT access tokens in Ory Hydra. When enabled, JWT access tokens are issued as self-contained tokens without persisting them to the database, significantly improving performance for high-throughput workloads.

Need help?

Overview​

By default, Ory Hydra persists all access tokens to the database, regardless of the token strategy (opaque or JWT). This persistence enables features like token introspection, revocation, and userinfo endpoint support. However, for workloads using JWT access tokens that do not require these stateful operations, database writes introduce unnecessary overhead.

The stateless JWT feature optimizes performance by skipping database persistence for JWT access tokens. When enabled, access tokens are issued as self-contained JWTs with a configurable boolean claim that identifies them as stateless. Operations that require token state (introspection, revocation, and userinfo) will return an error for these tokens.

This feature applies when either the OAuth2 client is configured to use the JWT access token strategy or the global access token strategy is set to JWT instead of opaque.

How it works​

When stateless JWT tokens are enabled:

  1. Token Generation: JWT access tokens are issued with an additional boolean claim (default: sl) set to true. This claim identifies the token as stateless.

  2. No Database Writes: Access token sessions are not written to the database, eliminating write operations and improving performance.

  3. Stateful Operations Unavailable: Operations that require token state return HTTP 501 (Not Implemented) with error unsupported_token_type:

    • Token Introspection (/oauth2/introspect): Returns 501 for stateless JWT tokens
    • Token Revocation (/oauth2/revoke): Returns 501 for stateless JWT tokens
    • Userinfo Endpoint (/userinfo): Returns 501 for stateless JWT tokens

  4. Standard JWT Validation: Token validation continues to work through standard JWT signature verification and claims validation.

Configuration​

Configure stateless JWT access tokens using the strategies.jwt.stateless configuration namespace.

Configuration keys​

Two configuration keys control stateless JWT behavior:

  • strategies.jwt.stateless.enabled: Boolean flag to enable or disable stateless JWT tokens. Default: false
  • strategies.jwt.stateless.claim_name: String value specifying the claim name used to identify stateless tokens. Default: sl

Example configuration​

strategies:
  jwt:
    stateless:
      enabled: true
      claim_name: sl

In this configuration:

  • Stateless JWT tokens are enabled
  • JWT access tokens will include a top-level claim "sl": true
  • Database writes for JWT access token sessions are skipped

Custom claim name​

You can customize the claim name used to identify stateless tokens:

strategies:
  jwt:
    stateless:
      enabled: true
      claim_name: stateless

With this configuration, JWT access tokens will contain "stateless": true instead of the default "sl": true.

Token format​

When stateless JWT tokens are enabled, the generated JWT access token includes the configured stateless claim as a top-level boolean claim.

Example JWT payload​

{
  "iss": "https://your-hydra-instance.com",
  "sub": "user-id",
  "aud": ["api-resource"],
  "exp": 1735689600,
  "iat": 1735686000,
  "scope": "openid profile email",
  "sl": true
}

The sl claim (or your custom claim name) with a boolean value of true identifies this token as stateless.

Functional limitations​

Enabling stateless JWT tokens disables certain OAuth2 and OpenID Connect features that require access to a persisted token state.

Token introspection​

Endpoint: /oauth2/introspect

When introspecting a stateless JWT access token, the endpoint returns:

  • HTTP Status: 501 Not Implemented
  • Error: unsupported_token_type

Standard opaque and JWT access tokens (with stateless disabled) continue to support introspection normally.

Token revocation​

Endpoint: /oauth2/revoke

Attempting to revoke a stateless JWT access token returns:

  • HTTP Status: 501 Not Implemented
  • Error: unsupported_token_type

Since stateless tokens are not persisted in the database, they cannot be revoked. Token expiration is enforced through the JWT exp claim during validation.

Userinfo endpoint​

Endpoint: /userinfo

Requesting user information with a stateless JWT access token returns:

  • HTTP Status: 501 Not Implemented
  • Error: unsupported_token_type

The /userinfo endpoint requires database lookups to retrieve the consent session data associated with the access token.