Enable the token exchange feature in Keycloak: start the server with '--features=token-exchange' or set the feature in keycloak.conf
In the Admin Console, navigate to the client that will perform the exchange and enable 'Token Exchange' under the Permissions tab; grant the exchanger client 'token-exchange' permission on the target client
The exchanger service obtains its own access token via client_credentials grant
Perform the token exchange: POST /realms/myrealm/protocol/openid-connect/token with grant_type=urn:ietf:params:oauth:grant-type:token-exchange, subject_token=<USER_TOKEN>, subject_token_type=urn:ietf:params:oauth:token-type:access_token, requested_token_type=urn:ietf:params:oauth:token-type:access_token, audience=<TARGET_CLIENT_ID>
The response contains an access_token scoped to the target audience with the user's identity; use it to call the downstream service
Audit the exchange: Keycloak logs token exchange events with the exchanger's client ID and the subject user; enable the Event Listener SPI to stream these to a SIEM
Known gotchas
Token exchange is a preview feature in Keycloak and may have breaking changes between releases; check the Keycloak release notes before upgrading
The permission grant must be made on the TARGET client's permissions UI, not the exchanger's; granting on the wrong client allows exchange to any audience
Without the explicit token-exchange permission grant, the exchange endpoint returns a 403 'Client not allowed to exchange' error even if the feature is enabled
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp