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 or MCP 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 is configured as a backend reference: a `host` in `host:port` form and, optionally, connection `policies` such as `backendTLS`. A `host` port of `443` automatically enables backend TLS.The following table describes the most common oauthTokenExchange fields. For the full set of fields, see oauthTokenExchange in the API reference for Kubernetes. The two modes take the same fields; standalone spells the enum values in camelCase, such as jwtBearer rather than JwtBearer.
| Field | Description |
|---|---|
host, policies | The token endpoint, referenced as a backend. A host port of 443 automatically enables backend TLS. |
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: clientSecretBasic (default), clientSecretPost, or privateKeyJwt. Omit the field and agentgateway sends no client authentication. See Authenticate the gateway to the token endpoint. |
audiences, scopes, resources | The audience, scope, and resource parameters sent to the token endpoint. resources are RFC 8707 resource indicators. |
subjectToken | Where to read the incoming token and its token type. Defaults to the Authorization: Bearer header with token type access_token. |
actorToken | Optional RFC 8693 delegation actor token (tokenExchange grant only). Has no default source. |
authorizationLocation | Where to place the exchanged token in the backend request. Defaults to the Authorization header with a Bearer prefix. |
additionalParams | Extra form parameters appended to the token request. Values are CEL expressions. |
cache | In-memory token cache. Defaults to 8192 entries with a 300-second TTL when the response omits expires_in. Set 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.
Cross App Access (ID-JAG)
Call a downstream API as the authenticated end user with the OAuth Identity Assertion Authorization …
