For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Token exchange
Exchange the token that a client sends to the gateway for a token that the backend accepts, by calling an OAuth authorization server.
Exchange the token that a client sends to the gateway for a token that the backend accepts, by calling an OAuth authorization server.
About
Instead of attaching a fixed credential to backend requests, the oauthTokenExchange backend authentication method exchanges the incoming token for a new, backend-specific token at an OAuth authorization server, then forwards that token to the backend. Token exchange is useful when a client authenticates to the gateway with one identity, but the backend requires a different, narrowly scoped token.
The gateway attaches the backend token itself, so the AI models and agents that call through it never see a backend credential. The user’s identity is preserved end-to-end, and the exchange can optionally carry an agent identity acting on behalf of the user (see actorToken), which keeps a consistent identity chain for auditing.
By default, the gateway reads the incoming token from the Authorization: Bearer header, exchanges it at the configured token endpoint, and attaches the returned token to the backend request in the Authorization: Bearer header.
Validation of the incoming token is the job of a route-level policy, such as JWT authentication, not the exchange itself. The exchange only reads the token and presents it to the authorization server.
Authorization servers that implement these grants include Keycloak, Microsoft Entra ID, Okta, Auth0, and ZITADEL.
Choose an exchange
Two backend authentication methods perform an exchange. Which one you need depends on how many authorization servers are involved.
| Method | Authorization servers | Use it when |
|---|---|---|
oauthTokenExchange | One | One server can issue the backend token from the incoming token. |
crossAppAccess | Two, across a trust boundary | The identity provider that authenticated the user and the authorization server that guards the resource are different parties. |
The oauthTokenExchange method supports two grants, and you choose between them with the grantType field.
| Grant | grantType | Standard | The incoming token is sent as |
|---|---|---|---|
| Token exchange (default) | TokenExchange | RFC 8693 | subject_token |
| JWT bearer | JwtBearer | RFC 7523 | assertion |
Some identity providers have vendor-specific variants of a grant. Microsoft Entra’s on-behalf-of flow is a variant of the JWT bearer grant, and the JWT bearer guide covers it.
Configuration
The token endpoint (authorization server) is configured as its own AgentgatewayBackend, which the AgentgatewayPolicy then references through backendRef. The gateway’s OAuth client secret is read from a Kubernetes Secret through clientAuth.secretRef. The policy attaches to the backend workload with targetRefs, so the exchange runs whenever the gateway forwards a request to that backend.
Review the following table to understand this configuration. For more information, see the API docs.
| Field | Description |
|---|---|
backendRef | Reference to the AgentgatewayBackend for the token endpoint. Mutually exclusive with url. Set exactly one of the two. |
url | The full address of the token endpoint, including the path. Use this field instead of backendRef to point at the authorization server directly, without creating an intermediate Kubernetes object. Mutually exclusive with backendRef. Do not set path when you use url. |
path | Path of the token endpoint on the backend. Must start with /. Defaults to /. |
grantType | TokenExchange (default, RFC 8693) or JwtBearer (RFC 7523). |
clientAuth | Client authentication for the token endpoint. method is ClientSecretBasic (default), ClientSecretPost, or PrivateKeyJwt. Use secretRef to read the client secret from a Kubernetes Secret. |
audiences, scopes, resources | The audience, scope, and resource parameters sent to the token endpoint. resources are RFC 8707 resource indicators. |
subjectToken.source | Where the gateway reads the incoming token from. Set exactly one of header, queryParameter, cookie, or expression, where expression is a CEL expression that reads the token from the request, such as a claim of a validated JWT. Defaults to the Authorization header with the Bearer prefix. |
subjectToken.tokenType | The type that the gateway reports for that token. Use a built-in name such as AccessToken (the default), Jwt, or IdToken, or a custom absolute URI. See Token types. |
actorToken | Optional RFC 8693 delegation actor token (TokenExchange grant only). Takes the same tokenType values as subjectToken. |
requestedTokenType | Optional token type to request, limited to AccessToken, Jwt, or IdToken, and valid only with the TokenExchange grant type. The response must return the type that you request. See Request a token type. |
location | Where to place the exchanged token in the backend request. Defaults to the Authorization header. |
additionalParams | Extra form parameters appended to the token request. Values are CEL expressions. |
cache | In-memory token cache. Defaults to 8192 entries. Set inMemory.maxEntries: 0 to disable. |
Standard token exchange (RFC 8693)
Exchange the incoming request credential for a per-backend token with the RFC 8693 token exchange …
JWT bearer grant (RFC 7523)
Exchange the incoming request credential for a per-backend token with the RFC 7523 JWT bearer grant.
Token exchange for MCP servers
Exchange the caller’s credential for a backend-scoped token before the gateway forwards a request to …
Cross App Access (ID-JAG)
Call a downstream API as the authenticated end user with the OAuth Identity Assertion Authorization …
