Skip to main content

Updating claims at token refresh

The Hydra OAuth2 and OpenID Connect server comes with a mechanism that allows updating id_token and access_token when a registered client sends a token refresh request. The flow is realized by calling the defined refresh token hook endpoint which returns updated data.

If the data provided by the webhook is different from the data the client sends, the webhook overwrites the session data with a new set.


The hook is called before any other logic is executed. If the hook execution fails, the entire token refresh flow fails and the refresh_token remains unused.


To enable the token refresh webhook, configure the oauth2.refresh_token_hook key in the Hydra configuration:


If you're running Hydra locally, you can set this value by exporting the refresh token hook endpoint URL as an environment variable. Run this command:


Webhook configuration

The refresh token hook endpoint must accept the following payload format:

"subject": "foo",
"client_id": "bar",
"granted_scopes": ["openid", "offline"],
"granted_audience": []

To update the data, the webhook must return a 200 OK response and the updated session data in the following format:

"session": {
"access_token": {
"foo": "bar"
"id_token": {
"bar": "baz"

The token subject is never overridden.

Updated tokens

The following examples show fragments of tokens issued after refreshing:

"aud": [
"auth_time": 1647427485,
"bar": "baz",
"iss": "http://ory.hydra.example/",
"sub": ""

Rejecting token refresh

To gracefully reject token contents update, the hook must return a 403 Forbidden response. Any other response results in a failure of the token update and, as a result, failure of the entire token refresh flow.