Configurable token prefix for OAuth2 tokens

This document explains how to configure the token prefix for OAuth2 access tokens, refresh tokens, and authorization codes. By default, all tokens use the ory_%s_ template, where %s is replaced with the token type.

Customizing the token prefix is available only to customers on an Ory Enterprise plan (Ory Network Enterprise or Ory Enterprise License). If you are interested in this feature, please contact us.

Default token prefix

By default, OAuth2 tokens use the following template: ory_%s_. The %s is a placeholder that will be replaced by the specific token type:

• rt for refresh tokens
• at for access tokens
• ac for authorization codes

Examples

• Refresh Token: ory_rt_...
• Access Token: ory_at_...
• Authorization Code: ory_ac_...

Customize the token prefix

With the oauth2.token_prefix configuration key, you can customize the prefix for your OAuth2 tokens.

The prefix must be a fmt.Sprintf-style template containing exactly one %s substitution. The rendered prefix may contain only ASCII letters, digits, and underscores - no other % directives (%d, %%, positional or width-flagged verbs), no hyphens, dots, slashes, whitespace, quotes, or non-ASCII characters. Invalid values are rejected with a 400 error.

Configure on Ory Network

On Ory Network, the prefix is set per project via the oauth2.token_prefix config key under services.oauth2.config. Use the Ory CLI:

ory patch oauth2-config --project <project-id> --workspace <workspace-id> \
  --replace '/oauth2/token_prefix="acme_token_%s_"'

To reset back to the default ory_%s_ prefix, remove the key:

ory patch oauth2-config --project <project-id> --workspace <workspace-id> \
  --remove "/oauth2/token_prefix"

Configure in self-hosted deployments

For Ory Enterprise License (OEL) deployments, set the oauth2.token_prefix key in your Ory configuration file:

oauth2:
  token_prefix: "acme_token_%s_"

Resulting tokens

With acme_token_%s_, issued tokens look like:

• Refresh Token: acme_token_rt_...
• Access Token: acme_token_at_...
• Authorization Code: acme_token_ac_...

JSON Web Tokens exception

JSON Web Tokens (JWTs) will never be prefixed because it would violate the JWT format. This applies to:

• ID Tokens: These are always JWTs and will never be prefixed.
• JWT Access Tokens: If you are using JWTs as access tokens, they will also not be prefixed.