From 96a92ea10556940648f96536d8710360ce672cce Mon Sep 17 00:00:00 2001 From: Arne Luenser Date: Wed, 20 May 2026 17:32:22 +0200 Subject: [PATCH] feat: hydra token prefixes --- docs/self-hosted/oel/oauth2/token-prefix.mdx | 38 ++++++++++++++------ sidebars-network.ts | 1 + 2 files changed, 28 insertions(+), 11 deletions(-) diff --git a/docs/self-hosted/oel/oauth2/token-prefix.mdx b/docs/self-hosted/oel/oauth2/token-prefix.mdx index 5edd7efd10..89d0faedec 100644 --- a/docs/self-hosted/oel/oauth2/token-prefix.mdx +++ b/docs/self-hosted/oel/oauth2/token-prefix.mdx @@ -9,8 +9,8 @@ sidebar_label: Customize token prefix 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 Enterprise License / Ory Network -Enterprise). If you are interested in this feature, please [contact us](https://www.ory.com/contact). +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](https://www.ory.com/contact). ## Default token prefix @@ -29,26 +29,42 @@ token type: ## Customize the token prefix -With the `oauth2.token_prefix` configuration key, you can customize the prefix for your OAuth2 tokens. This key is only available -to Ory Enterprise License customers. +With the `oauth2.token_prefix` configuration key, you can customize the prefix for your OAuth2 tokens. -### How to configure +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. -1. **Locate the Configuration File**: Open your Ory configuration file. -2. **Set the `oauth2.token_prefix` Key**: Add or modify the `oauth2.token_prefix` key in your configuration file. +### Configure on Ory Network -### Example configuration +On Ory Network, the prefix is set per project via the `oauth2.token_prefix` config key under `services.oauth2.config`. Use the +[Ory CLI](../../../guides/cli/installation): + +```shell +ory patch oauth2-config --project --workspace \ + --replace '/oauth2/token_prefix="acme_token_%s_"' +``` + +To reset back to the default `ory_%s_` prefix, remove the key: + +```shell +ory patch oauth2-config --project --workspace \ + --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: ```yaml oauth2: token_prefix: "acme_token_%s_" ``` -In this example, tokens will use the `acme_token_%s_` template. The `%s` placeholder for the token type must always be included in -the template. - ### 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_...` diff --git a/sidebars-network.ts b/sidebars-network.ts index 56eb11aba6..df74a6dec4 100644 --- a/sidebars-network.ts +++ b/sidebars-network.ts @@ -532,6 +532,7 @@ const networkSidebar = [ "hydra/guides/jwt", "hydra/guides/client-token-expiration", "hydra/guides/graceful-token-refresh", + "self-hosted/oel/oauth2/token-prefix", "oauth2-oidc/claims-scope", ], },