Token Exchange

Availability

Feature	Editions
Token exchange	Enterprise

Available from Tyk 5.14.0

Introduction

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.

How it works

When a request arrives at a Tyk API with token exchange enabled:

Tyk validates the inbound bearer token using the configured oauth2 security scheme.
If scope enforcement is enabled, Tyk checks the token’s scopes against the operation’s security: requirements.
Tyk reads the iss claim from the validated token and matches it against the issuers list on each configured provider.
Tyk POSTs an RFC 8693 exchange request to the matched provider’s tokenEndpoint, presenting the inbound token as subject_token.
The authorization server returns a new access token. Tyk replaces the Authorization header with the exchanged token.
Tyk forwards the modified request upstream.

If no configured provider’s issuers list matches the inbound token’s iss claim, Tyk returns 403 Forbidden with error="no_matching_provider".

Configure token exchange

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.

Minimal example

x-tyk-api-gateway:
  server:
    authentication:
      enabled: true
      securitySchemes:
        idpAuth:
          enabled: true
          tokenExchange:
            enabled: true
            providers:
              - name: keycloak-prod
                issuers:
                  - https://idp.example.com/realms/demo
                tokenEndpoint: https://idp.example.com/realms/demo/protocol/openid-connect/token
                clientAuth:
                  method: client_secret_basic
                  clientId: tyk-gateway
                  clientSecret: env://EXCHANGE_CLIENT_SECRET
                defaultTarget:
                  audience: https://api.internal.example.com
                  scopes:
                    - api:read
                    - api:write

String fields in the API definition accept env://, secrets://, vault://, and consul:// prefixes so sensitive values are not stored directly in the definition.

Provider fields

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.
`clientAuth.clientSecret`	string	No	Client secret. Accepts `env://`, `secrets://`, `vault://`, `consul://` prefixes.
`defaultTarget.audience`	string	No	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.

Grant Type

Available from Tyk 5.15.0.

providers:
  - name: corp-idp
    grantType: jwt-bearer
    issuers:
      - https://idp.example.com
    tokenEndpoint: https://idp.example.com/token
    clientAuth:
      method: client_secret_post
      clientId: tyk-gateway
      clientSecret: env://EXCHANGE_CLIENT_SECRET
    defaultTarget:
      audience: api://orders
      scopes:
        - Orders.Read

Field	Type	Required	Description
`grantType`	string	No	`token-exchange` (default) sends the RFC 8693 token-exchange grant; `jwt-bearer` sends the RFC 7523 jwt-bearer grant.

See Microsoft Entra ID On-Behalf-Of for a walkthrough of configuring grantType: jwt-bearer.

Under grantType: jwt-bearer, the exchange request differs from RFC 8693 in three ways:

Tyk Gateway sends the inbound token as assertion, not subject_token. None of the RFC 8693 subject-token fields are sent under this grant.
No audience or resource wire parameter is ever sent. The audience is folded into scope instead, using the rendering rule below.
Only assertion is a reserved customParams key, so a literal audience or resource custom parameter is forwarded if your authorization server expects one on this grant.

Scope Rendering

The configured audience and scopes describe the same logical target under both grants, but jwt-bearer renders them differently:

Each scope that does not already contain a / is prefixed with audience/.
A scope that already contains a / is treated as fully qualified and passed through verbatim.
If no scopes are configured, no scope parameter is sent.

Configured Target	Scope Sent Under jwt-bearer
`audience: api://orders`, `scopes: [Orders.Read]`	`scope=api://orders/Orders.Read`
`audience: api://orders`, `scopes: [Orders.Read, https://graph.microsoft.com/.default]`	`scope=api://orders/Orders.Read https://graph.microsoft.com/.default`
No `audience`, `scopes: [read, write]`	`scope=read write`
`audience: api://orders`, no `scopes`	No `scope` parameter is sent

Example: Provider Without an Audience

An authorization server that implements plain RFC 7523, such as Keycloak, needs no customParams. Leave audience out and write the scopes exactly as your authorization server defines them:

providers:
  - name: keycloak-jwt-bearer
    grantType: jwt-bearer
    issuers:
      - https://idp.example.com/realms/acme
    tokenEndpoint: https://idp.example.com/realms/acme/protocol/openid-connect/token
    clientAuth:
      method: client_secret_post
      clientId: tyk-gateway
      clientSecret: env://EXCHANGE_CLIENT_SECRET
    defaultTarget:
      scopes:
        - orders.read
        - orders.write

This sends scope=orders.read orders.write.

RFC 7523 Section 3 requires the inbound token’s aud claim to already name this authorization server’s token endpoint. That is a precondition on how the token was issued, not something this configuration controls.

If your authorization server also expects an explicit downstream resource (RFC 8707), pass it through customParams. Under jwt-bearer, resource is not reserved, so it is forwarded unchanged alongside the rendered scope:

customParams:
  resource: https://orders.example.com

Client Authentication

clientAuth.method supports client_secret_basic (default) and client_secret_post under both grants, plus private_key_jwt, which authenticates using a signed client-assertion JWT (RFC 7523 Section 2.2) instead of a shared secret:

Field	Type	Required	Description
`clientAuth.method`	string	No	One of `client_secret_basic` (default), `client_secret_post`, or `private_key_jwt`.
`clientAuth.certId`	string	Conditional	Required when `method` is `private_key_jwt`. References a certificate already uploaded to Tyk Gateway’s certificate store. Its private key signs the client assertion.

The client assertion is short-lived (5 minutes) and its JOSE header carries the certificate’s SHA-256 thumbprint (x5t#S256), so the authorization server can select the matching registered key.

private_key_jwt supports RSA-signed certificates only (RS256). EC keys are not supported.

Step-Up Authentication

Under grantType: jwt-bearer, if the authorization server responds with "error":"interaction_required", meaning the end user must sign in again, Tyk Gateway does not treat this as an ordinary exchange failure. It returns 401 Unauthorized to the original caller with a WWW-Authenticate: Bearer error="insufficient_claims" header, relaying the authorization server’s claims challenge (base64-standard-encoded) and authorization_uri when supplied. No upstream call is made and nothing is cached. A caller such as an MSAL-based client can then complete the required step-up, for example an Entra Conditional Access or MFA challenge, and retry. This relay is scoped to the jwt-bearer grant. The same interaction_required error under the default token-exchange grant is treated as an ordinary idp_error failure. The relay records the step_up_required outcome described in Observability.

Multi-Tenant Issuer Matching

Some authorization servers issue a different iss per tenant, with no way to enumerate every tenant up front. Two opt-in mechanisms cover this:

An issuers entry prefixed with regex: is matched as a compiled regular expression against the inbound token’s iss claim. Entries without the prefix keep exact-match semantics. Dispatch is deterministic: exact-match entries are checked first, across all providers; only if none match does Tyk Gateway try regex: entries, in provider order, first match wins.
tokenEndpoint accepts Tyk’s standard $tyk_context.* request-time variables, so one provider entry can serve many tenants from a single token endpoint template. For example, $tyk_context.jwt_claims_tid reads a tid claim from the validated JWT. The resolved endpoint is re-validated as an absolute http(s) URL at request time, and Tyk Gateway keys the token cache by the resolved endpoint so a cached token is never served to the wrong tenant.

A regex: issuer entry controls routing to a provider, not trust. Which tenants are allowed to authenticate is decided by the JWT authentication scheme’s allowedIssuers list, which verifies the token’s signature before token exchange runs. Pairing a permissive regex: entry with an empty or permissive allowedIssuers accepts any tenant of that authorization server, so set allowedIssuers deliberately.

Caching

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:

providers:
  - name: keycloak-prod
    ...
    cache:
      enabled: true
      mode: derived
      maxTimeout: 5m
      safetyMargin: 30s

Field	Type	Default	Description
`enabled`	boolean	`false`	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.

Per-operation override

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:

x-tyk-api-gateway:
  middleware:
    operations:
      getInternalReport:
        exchange:
          enabled: true
          audience: https://reporting.internal.example.com
          scopes:
            - reports:read

Field	Type	Description
`enabled`	boolean	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.

Per-MCP-primitive override

For MCP Gateway deployments, you can override the exchange target per primitive using middleware.mcpTools, middleware.mcpResources, or middleware.mcpPrompts:

x-tyk-api-gateway:
  middleware:
    mcpTools:
      create-report:
        exchange:
          enabled: true
          audience: https://reporting.internal.example.com
          scopes:
            - reports:write

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.

Scope inference

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.

Known limitations

The following limitations apply in Tyk 5.15.0:

private_key_jwt key support: private_key_jwt client authentication (used with the jwt-bearer grant) supports RSA-signed certificates only (RS256). EC keys are not supported.
Actor token delegation: RFC 8693 defines an optional actor-token mechanism for representing a delegation chain (for example, a service acting on behalf of another service, which is itself acting on behalf of a user). Tyk does not currently implement this — token exchange always presents the gateway as the sole confidential client, with no actor token in the request. There is no actorToken configuration field.

Observability

Available from Tyk 5.15.0. Every token exchange decision emits an OpenTelemetry metric, a structured log line, a dedicated trace span and an audit event for authorization outcomes. You can see exchange volume and IdP latency, alert on error rates by provider, and trace a single request through the exchange step and the IdP round-trip it triggered.

Metrics

See Token Exchange Metrics for the full instrument and dimension reference.

Structured logs

Tyk writes one JSON log line per exchange decision, using stable, oauth2_-namespaced field names so you can wire SIEM or alerting rules directly to them:

Field	Description
`trace_id`	The OpenTelemetry trace ID for the request. Matches the `trace_id` on the gateway access log line for the same request, so you can join the two.
`oauth2_api_id`	The Tyk API ID the exchange ran on.
`oauth2_provider`	The provider `name` that matched the inbound token.
`oauth2_exchange_outcome`	One of `ok`, `idp_error`, `misconfig`, `no_matching_provider`, or `step_up_required` (`jwt-bearer` grant only).
`oauth2_exchange_cache_hit`	Whether the exchanged token was served from cache.
`duration_ms`	Time taken to obtain the exchanged token, in milliseconds.
`oauth2_idp_error` / `oauth2_idp_error_description`	The authorization server’s error code and description. Present only on an `idp_error` outcome, and length-capped so an oversized or malicious IdP response cannot bloat the log line.
`oauth2_subject_azp`	The `azp` (authorized party) of the inbound token — the client application the token was issued to.
`oauth2_exchanged_azp`	The `azp` of the exchanged token, when the authorization server returns one.
`oauth2_audience`	The audience requested for the exchanged token.
`oauth2_scopes_requested`	The scopes requested for the exchanged token.

{
  "level": "info",
  "msg": "oauth2 token exchange",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "oauth2_api_id": "a1b2c3d4e5f6",
  "oauth2_provider": "keycloak-prod",
  "oauth2_exchange_outcome": "ok",
  "oauth2_exchange_cache_hit": false,
  "duration_ms": 42,
  "oauth2_subject_azp": "agent-frontend",
  "oauth2_audience": "https://api.internal.example.com",
  "oauth2_scopes_requested": ["api:read", "api:write"]
}

Following OWASP’s logging guidance best practices, Tyk omits the inbound token’s jti and sub claims from the log line. The azp fields above already answer which application acted, for which audience, with what scopes, and with what outcome, without exposing an end user’s identity.

Audit events

Tyk fires an audit event for every exchange decision that represents an authorization outcome:

Outcome	Audit event
`ok` (including cache hits)	`OAuth2ExchangeSucceeded`
`idp_error`	`OAuth2ExchangeFailed`
`no_matching_provider`	`OAuth2ExchangeFailed`
`misconfig`	Not audited
`step_up_required` (`jwt-bearer` grant only)	Not audited — this is an expected control-flow event relaying a caller-side action, not a failure

A cache hit still fires OAuth2ExchangeSucceeded, because a backend call is still being made on the subject’s behalf even though the exchanged token itself came from cache rather than a fresh round-trip to the authorization server.

misconfig does not produce an audit event. An unresolvable client secret or other configuration fault is an operational error, not an authorization decision made by the IdP, so it’s surfaced only through the metric and log line.

The audit event’s metadata carries the same oauth2_-namespaced fields as the structured log line: the provider, outcome, audience, requested scopes, the azp client identifiers, and the IdP error code and description when applicable. As with the logs, no raw token material, jti, or sub ever appears in audit metadata.

Distributed tracing

Token exchange opens a dedicated oauth2.exchange span for every attempt, nested inside the request’s existing trace after the inbound token is identified and before the request reaches the upstream proxy. This is a real child span from the OpenTelemetry tracer, not attributes stamped onto the inbound request span, so the exchange step shows up as its own node in the trace. The span carries three attributes, using the same bounded values as the metric labels and log fields:

Attribute	Description
`oauth2.exchange.provider`	The matched provider name.
`oauth2.exchange.outcome`	One of `ok`, `idp_error`, `misconfig`, `no_matching_provider`, or `step_up_required` (`jwt-bearer` grant only).
`oauth2.exchange.cache_status`	`hit` or `miss`.

On a cache miss, the call to the authorization server’s token endpoint appears as a child HTTP client span under oauth2.exchange, since Tyk’s IdP client is already traced. On a cache hit, there’s no such child span at all — the trace shows the absence of a round-trip. This makes it easy to tell, at a glance, whether a given request paid the cost of a live IdP call or was served entirely from cache. Put together, a single trace shows the inbound request, the exchange decision, the IdP round-trip (or its absence), and the upstream call, in order.

Token exchange and upstream auth

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.

Getting Started

Deploy Tyk

Design & Create APIs

Secure APIs

Control Traffic

Routing Traffic

Transform Traffic

Observe APIs

Maintain APIs

Use Cases

Guides

Reference

Developer Support

Availability

Introduction

How it works

Configure token exchange

Minimal example

Provider fields

Grant Type

Scope Rendering

Example: Provider Without an Audience

Client Authentication

Step-Up Authentication

Multi-Tenant Issuer Matching

Caching

Per-operation override

Per-MCP-primitive override

Scope inference

Known limitations

Observability

Metrics

Structured logs

Audit events

Distributed tracing

Token exchange and upstream auth

​Availability

​Introduction

​How it works

​Configure token exchange

​Minimal example

​Provider fields

​Grant Type

​Scope Rendering

​Example: Provider Without an Audience

​Client Authentication

​Step-Up Authentication

​Multi-Tenant Issuer Matching

​Caching

​Per-operation override

​Per-MCP-primitive override

​Scope inference

​Known limitations

​Observability

​Metrics

​Structured logs

​Audit events

​Distributed tracing

​Token exchange and upstream auth

Availability

Introduction

How it works

Configure token exchange

Minimal example

Provider fields

Grant Type

Scope Rendering

Example: Provider Without an Audience

Client Authentication

Step-Up Authentication

Multi-Tenant Issuer Matching

Caching

Per-operation override

Per-MCP-primitive override

Scope inference

Known limitations

Observability

Metrics

Structured logs

Audit events

Distributed tracing

Token exchange and upstream auth