How to Use Okta's Token Inline Hooks to Add/Modify Claims Based on Parameters Included in an /Authorize Request
Last Updated:
Overview
Using Token Inline Hooks, it is possible to enrich an ID and/or Access Tokens issued by a Custom Authorization Server based on the request parameters included in the /authorize (for example, for Implicit and Authorization Code flow) or /token request (for example, for Resource Owner Password Grant, Token Renewals). If the OpenID Connect/OAuth 2.0 application sends additional URL parameters in this request, when Okta sends to the hook endpoint, the request payload will contain the full URL to Okta for the token request. The hook endpoint can then parse that URL and dynamically use this information in the commands sent by the hook endpoint to modify the tokens being issued.
Applies To
- Okta Identity Engine (OIE)
- Okta Classic Engine
- API Access Management
- Custom Authorization Server
- Token Inline Hooks
Solution
How is a Token Inline hook used to modify tokens based on request parameters?
The full request URL for the request will be available in the request payload sent to the Token Inline Hook endpoint. Any additional parameters included in the request made to Okta will be ignored by Okta but will still be included in the request payload sent to the hook endpoint, thus allowing the application to send dynamic values to the /authorize and the /token endpoint that can be used to drive logic for the Token Inline Hook endpoint (such as adding this value as a claim in the resultant token).
Depending on the flow being executed, the extra parameters can be included within the /authorize request URL or the /token request URL. For example, if the application in question uses the Authorization Code flow, this parameter can be included in the /authorize request when the application first requests tokens for the user and in the /token request when the application renews the user's tokens with a refresh token.
The full request URL for the /authorize or /token request that triggered the hook execution can be found within the data.context.url.value object in the request payload (see example payload below)
Examples of URLs With an Extra Request Parameter
Authorize Eequest URL
https://oktaDomain/oauth2/aus1234567890/v1/authorize?client_id=0oa1234567890&scope=openid+profile&redirect_uri=https://example.com&response_type=code&state=asbn5dasau141n3io13&nonce=foo&extraParam=this_is_an_extra_parameterToken Request URL
https://oktaDomain/oauth2/aus1234567890/v1/token?extraParam=this_is_an_extra_parameter
Example Inline Hook Payload
{
"eventId": "<eventId>",
"eventTime": "2026-07-03T18:51:51.000Z",
"eventType": "com.okta.oauth2.tokens.transform",
"eventTypeVersion": "1.0",
"contentType": "application/json",
"cloudEventVersion": "0.1",
"source": "https://oktaDomain/oauth2/aus1234567890/v1/token",
"data": {
"context": {
"request": {
"id": "<id>",
"method": "POST",
"url": {
"value": "https://oktaDomain/oauth2/aus1234567890/v1/token?extraParam=this_is_a_refresh"
},
"ipAddress": "<ipAddress>"
},
"protocol": {
"type": "OAUTH2.0",
"request": {
"scope": "offline_access openid profile",
"grant_type": "refresh_token",
"client_id": "0oa01234567890"
},
"originalGrant": {
"authorization": {
"scope": "profile offline_access openid",
"redirect_uri": "https://example.com",
"response_type": "code",
"grant_type": "authorization_code"
},
"refresh_token": {
"jti": "oar1234567890"
}
},
"issuer": {
"uri": "https://oktaDomain/oauth2/aus1234567890"
},
"client": {
"id": "0oa01234567890",
"name": "Web App",
"type": "PUBLIC"
}
},
"session": {
"id": "<id>",
"userId": "00u1234567890",
"login": "user@example.com",
"createdAt": "2026-07-03T18:50:52.000Z",
"expiresAt": "2026-07-03T20:51:51.000Z",
"status": "ACTIVE",
"lastFactorVerification": "2026-07-03T18:50:51.000Z",
"amr": [
"PASSWORD"
],
"mfaActive": false
},
"user": {
"id": "00u1234567890",
"passwordChanged": "2025-10-28T00:27:44.000Z",
"profile": {
"login": "user@example.com",
"firstName": "Test",
"lastName": "User",
"locale": "en",
"timeZone": "America/Los_Angeles"
},
"_links": {
"groups": {
"href": "https://oktaDomain/api/v1/users/00u1234567890/groups"
},
"factors": {
"href": "https://oktaDomain/api/v1/users/00u1234567890/factors"
}
}
},
"policy": {
"id": "00p1234567890",
"rule": {
"id": "0pr1234567890"
}
}
},
"identity": {
"claims": {
"sub": "00u1234567890",
"name": "Test User",
"ver": 1,
"iss": "https://oktaDomain/oauth2/aus1234567890",
"aud": "0oa01234567890",
"jti": "ID.12345678912345678",
"amr": [
"swk",
"mfa",
"pwd"
],
"idp": "00o1234567890",
"sid": "<>",
"preferred_username": "test.user",
"auth_time": 1720032651
},
"token": {
"lifetime": {
"expiration": 3600
}
}
},
"access": {
"claims": {
"ver": 1,
"jti": "AT.12345678",
"iss": "https://oktaDomain/oauth2/aus1234567890",
"aud": "/hooks",
"cid": "0oa01234567890",
"uid": "00u1234567890",
"auth_time": 1720032651,
"sub": "test.user"
},
"token": {
"lifetime": {
"expiration": 3600
}
},
"scopes": {
"openid": {
"id": "scpfhu4svvZ4Gl6Pm1d7",
"action": "GRANT"
},
"offline_access": {
"id": "scpfhu4sw0Zasc1oD1d7",
"action": "GRANT"
},
"profile": {
"id": "scpfhu4svwnGvLJ9x1d7",
"action": "GRANT"
}
}
},
"refresh_token": {
"jti": "oar1234567890"
}
}
}
