What Is Token Exchange: RFC 8693 vs Custom

Token exchange means “this proof, a different token”

RFC 8693 defines an OAuth 2.0 grant, urn:ietf:params:oauth:grant-type:token-exchange, for swapping an existing token for a new one. Typical reasons: the incoming token’s aud is your gateway, the upstream API wants a token minted for its audience; or a user token must become a narrower service token before an agent calls a third-party API.

  subject_token (audience: gateway)
           |
           v
  POST /token
  grant_type=urn:ietf:params:oauth:grant-type:token-exchange
  audience=https://api.vendor.example
           |
           v
  access_token (audience: vendor)

The new token is not a refresh of the old one. Refresh keeps the same grant alive and usually the same audience. Exchange is a new issuance, with its own scope, resource, and audience parameters.

RequestRocket does not implement RFC 8693 as a grantType. The oauth2 grants are authorization_code, pkce, client_credentials, and password. If you need the RFC 8693 grant specifically, that is still a conversation with the authorization server, not a credential type we expose.

Three things people call “token exchange”

The phrase gets used for three different on-the-wire patterns. Mixing them up produces the wrong credential.

1. RFC 8693 token exchange. A standards-based POST to an OAuth token endpoint with grant_type=urn:ietf:params:oauth:grant-type:token-exchange, a subject_token, and usually audience or resource. Output is a new access token (and maybe a refresh token). We do not model this grant.

2. OAuth refresh. grant_type=refresh_token. Same client, typically same audience, new access token. This is handled on oauth2 target credentials via stored refreshToken, refreshURL, and tokenExpiresIn. See What is OAuth 2.0.

3. Vendor login / custom token endpoints. POST /login or POST /api/token with a proprietary JSON body, a token buried at data.access_token, expiry as expires_at in milliseconds. Conceptually “swap a durable secret for a short-lived token,” but not OAuth. This is the pattern RequestRocket models as customToken.

POST /v1/login HTTP/1.1
Host: api.vendor.example
Content-Type: application/json

{ "user": "svc", "secret": "..." }

{ "data": { "access_token": "abc123", "expires_in": 3600 } }

A gateway that can call that endpoint, parse a dotted path, interpret four expiry encodings, and attach the token on subsequent calls is doing custom token exchange without pretending it is RFC 8693.

What customToken actually requires

Target credentials only. Required secret fields: tokenLocation (header | query | body – where the token sits in the token-endpoint response), tokenPath (for example access_token or data.access_token), key (the header or query name to send upstream), and addToHeader.

Optional but where the work lives:

• tokenURL and tokenMethod (GET | POST) – the endpoint to call.
• tokenHeaders, tokenQueryParams, tokenData – what you send to the token endpoint (as opposed to additionalHeaders on the upstream request).
• tokenExpiryPath plus tokenExpiryMethod: expires_in (seconds from now), expires_in_ms, expires_at (unix seconds), expires_at_iso. Getting the method wrong is how tokens are refreshed an hour late or a thousand times a second.

We split token-endpoint parameters from upstream parameters on purpose. Folding them into one map is how teams leak a login password into the vendor API request, or send X-API-Key to the login URL that does not expect it.

When you actually need RFC 8693

You need the RFC when the authorization server already implements it and the upstream will only accept a token whose aud is that API. Identity platforms (some Entra, Curity, Keycloak setups) use it for on-behalf-of flows. A generic “fetch a token from this URL” credential will not set grant_type to the RFC 8693 URN unless you put that field in tokenData yourself – and even then you are using customToken as a generic HTTP client, not as a first-class grant.

If the survey of every upstream scheme is what you wanted, that is API authentication methods explained.

Next steps

For a proprietary login URL, create a customToken target credential and set tokenPath / tokenExpiryMethod from a real response body, not from the vendor’s marketing docs. The field reference is in the credentials guide. RequestRocket is runtime access control for AI agents and apps calling APIs you don’t own – every call gets a least-privilege credential, a policy check, and an audit record, with no code changes.