Token exchange (RFC 8693) is a client authentication feature that replaces the inbound bearer token with a backend-scoped token before forwarding a request to the upstream service. Tyk Gateway presents itself as a confidential client to an external authorization server, exchanges the inbound token for one audienced to the upstream, and injects the result into the Authorization header. The inbound token never reaches the upstream service.This approach addresses two common problems in multi-service architectures and MCP Gateway deployments:
Token audience mismatch: An SSO or agent token issued for Tyk is not accepted by the upstream service, which expects a token carrying its own audience claim.
Audit trail continuity: The raw inbound token is not forwarded to the upstream. The upstream receives a token scoped to its own audience, issued after the exchange, which keeps the token chain auditable at the authorization server level.
Token exchange runs in the middleware chain after scope enforcement and before the reverse proxy.
In open source deployments, token exchange does not execute at runtime. The inbound token is forwarded to the upstream unchanged, and an error is logged.
Token exchange is configured under tokenExchange within the oauth2 security scheme in your Tyk OAS API definition. The oauth2 scheme must be enabled on the API; see OAuth 2.0 (External IdP). You must configure at least one provider.
Token exchange reads the iss claim from the inbound bearer token at request time. The oauth2 scheme does not validate the token’s JWT signature itself in Tyk 5.14.0. JWT authentication must be configured on the API so that the inbound token is verified before the exchange middleware runs. Without a JWT auth method configured, Tyk’s auth chain will reject the request before token exchange is reached.
String fields in the API definition accept env://, secrets://, vault://, and consul:// prefixes so sensitive values are not stored directly in the definition.
Each entry in providers matches inbound tokens by iss claim and routes exchange requests to the corresponding token endpoint. Provider names must be unique, and issuer values must not overlap across providers.
Field
Type
Required
Description
name
string
Yes
Operator-assigned identifier used in log output. Must be unique across providers.
issuers
array of strings
Yes
Inbound token iss values routed to this provider. Must not overlap with issuers declared on other providers.
tokenEndpoint
string
Yes
Authorization server token endpoint. Must accept grant_type=urn:ietf:params:oauth:grant-type:token-exchange.
clientAuth.method
string
No
How Tyk authenticates to the token endpoint: client_secret_basic (default) sends credentials in the Authorization header; client_secret_post sends them in the request body.
clientAuth.clientId
string
Yes
Client ID Tyk presents to the authorization server.
Default audience requested for the exchanged token. Applied when no per-operation override is set.
defaultTarget.scopes
array of strings
No
Default scopes requested. Applied when no per-operation override is set.
timeout
duration string
No
Per-call timeout for requests to tokenEndpoint. Accepts values such as "5s" or "500ms". Defaults to "15s".
customParams
map
No
Additional form parameters appended to the exchange request. Standard RFC 8693 keys (grant_type, subject_token, audience, and others) are reserved and cannot be overridden.
Tyk can cache exchanged tokens in Redis to avoid a round-trip to the authorization server on every request. Configure caching under cache within a provider:
Enables Redis-backed caching for this provider’s exchanged tokens.
mode
string
"derived"
How the cache TTL is computed. "derived": TTL is min(expiresIn, inboundRemaining, maxTimeout) − safetyMargin, where expiresIn is the exchanged token’s lifetime, inboundRemaining is the inbound token’s remaining life, and maxTimeout is an optional operator ceiling. "static": TTL is min(timeout, expiresIn) − safetyMargin; the exchanged token’s expiry still acts as an upper bound even in fixed-TTL mode.
maxTimeout
duration string
-
Optional operator ceiling on the cache TTL in "derived" mode (for example, "5m"). Has no effect in "static" mode.
timeout
duration string
-
Fixed cache TTL in "static" mode (for example, "2m"). Still clamped by the exchanged token’s expiry.
safetyMargin
duration string
"30s"
Duration subtracted from the computed TTL to avoid serving near-expired tokens. Applies in both modes.
The defaultTarget on a provider applies to all requests routed to that provider. To request a different audience or scope set for a specific operation, add an exchange block under the matching operation in middleware.operations:
Activates this per-operation override. When false or absent, the provider’s defaultTarget is used.
audience
string
Audience requested for this operation’s exchanged token.
scopes
array of strings
Explicit scope list for this operation. When empty and enabled is true, scopes are inferred from the operation’s security: declaration; see Scope inference.
For MCP Gateway deployments, you can override the exchange target per primitive using middleware.mcpTools, middleware.mcpResources, or middleware.mcpPrompts:
The exchange block on a primitive has the same fields as the per-operation block. This lets you route different primitives to different downstream audiences within a single provider. For example, read tools to a read-only service and write tools to an elevated-privilege service.
When a per-operation or per-primitive exchange block has enabled: true but scopes is empty, Tyk infers the scope list from the operation’s or primitive’s security: declaration. The scopes required by the operation’s security requirements are sent as the requested scope to the authorization server, aligning the exchanged token’s scope with what the upstream is expected to require (RFC 8693 §4.5.5).If you prefer explicit control over the requested scopes, set scopes to a non-empty list.
Do not configure upstream.authentication.oauth alongside token exchange. Token exchange replaces the Authorization header with the exchanged token before the reverse proxy; it is the upstream credential. The upstream.authentication block is for a separate scenario where Tyk authenticates to the upstream using its own static credentials, independent of any inbound token. Configuring both will produce a conflict.
