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.

When to use stateless JWT tokens​

Stateless JWT access tokens are suitable for scenarios where:

  • High throughput is required: Applications with high token issuance rates benefit from eliminating database writes
  • Token revocation is not needed: Workloads that rely solely on JWT expiration for token lifecycle management
  • Introspection is not used: Resource servers validate tokens using JWT signature verification rather than introspection
  • Userinfo endpoint is not required: Client applications do not call the userinfo endpoint for user information
  • JWT access tokens are used: The feature only applies when clients or the global strategy is configured for JWT tokens

When not to use stateless JWT tokens​

Do not enable stateless JWT tokens if your application requires:

  • Token revocation: Immediate invalidation of access tokens before expiration
  • Token introspection: Validating tokens through the introspection endpoint
  • Userinfo endpoint support: Retrieving user information associated with access tokens
  • Audit trail of active tokens: Database records of issued tokens for compliance or auditing purposes

Performance considerations​

Enabling stateless JWT tokens provides performance benefits by:

  • Eliminating database write operations for access token sessions
  • Decreasing storage requirements by not persisting JWT access tokens