melodic-oil-50942
04/17/2025, 7:41 PMbrief-egg-61061
04/17/2025, 7:41 PMbrief-egg-61061
04/17/2025, 7:42 PM/oauth2/token
endpoint using OAuth2 webhooks. This feature allows you to add custom claims to both ID tokens and access tokens issued by Ory OAuth2/Ory Hydra. ## How to customize token claims You can register a webhook endpoint in your OAuth2 configuration. Before the token is issued to the client, Ory will call your HTTPS endpoint with information about the OAuth client requesting the token. Your endpoint's response will be used to customize the token that Ory issues. ### Configuration Use the Ory CLI to register your webhook endpoint: ory patch oauth2-config --project <project-id> --workspace <workspace-id> \ --add '/oauth2/token_hook/url="<https://my-example.app/token-hook>"' \ --add '/oauth2/token_hook/auth/type="api_key"' \ --add '/oauth2/token_hook/auth/config/in="header"' \ --add '/oauth2/token_hook/auth/config/name="X-API-Key"' \ --add '/oauth2/token_hook/auth/config/value="MY API KEY"' \ --format yaml
### Responding to the webhook To modify the claims of the issued tokens, your webhook should return a 200
status code with a JSON response body like: {
"session": {
"access_token": {
"your:custom:access-token-claim": "any value you like",
"your:second:access-token-claim": 124390123
},
"id_token": {
"your:custom:id-token-claim": "another value",
"your:second:id-token-claim": 2394123
}
}
}
The custom claims for access tokens will appear in the ext
field when the token is introspected, while ID token claims will appear directly in the token payload. Note that you cannot override the token subject. [Customizing claims with OAuth2 webhooks](https://www.ory.sh/docs/hydra/guides/claims-at-refresh) provides detailed documentation on this feature, including webhook payload examples and configuration options. For the Resource Owner Password Credentials grant specifically, you can also see examples of the resulting token claims in the [OAuth2 resource owner password credentials grant](https://www.ory.sh/docs/oauth2-oidc/resource-owner-password-grant) documentation.