--- title: Token exchange grant description: You can configure the PingFederate OAuth server to support the token exchange grant type. component: pingfederate version: 12.2 page_id: pingfederate:introduction_to_pingfederate:pf_token_exchange_grant canonical_url: https://docs.pingidentity.com/pingfederate/13.1/introduction_to_pingfederate/pf_token_exchange_grant.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: July 29, 2026 superseded_by: https://docs.pingidentity.com/pingfederate/13.1/introduction_to_pingfederate/pf_token_exchange_grant.html section_ids: example-use-case: Example use case internal-pingfederate-processing: Internal PingFederate processing --- # Token exchange grant You can configure the PingFederate OAuth *(tooltip: \
\

A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server.\

\
)* server to support the token exchange *(tooltip: \
\

The process by which a security token is exchanged for another security token.\

\
)* grant type. This feature uses the protocol defined in the OAuth 2.0 token exchange specification RFC 8693. Learn more about OAuth 2.0 token exchange in [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693). Learn more about configuring the OAuth server for token exchange in [OAuth token exchange](../administrators_reference_guide/pf_oauth_exchange.html). PingFederate supports the following token types: * `urn:ietf:params:oauth:token-type:access_token` * `urn:ietf:params:oauth:token-type:saml1` * `urn:ietf:params:oauth:token-type:saml2` * `urn:params:oauth:token-type:jwt` A token exchange begins when a OAuth client *(tooltip: \
\

The application in an OAuth framework that requests access to resources. If the request is approved by the authorization server, the client is issued an access token for the resources.\

\
)* sends a token exchange request to the PingFederate OAuth authorization server (OAuth AS) *(tooltip: \
\

The authorizing service in an OAuth framework that issues and manages access tokens for clients to access protected resources.\

\
)*. The request contains the token exchange grant type parameter, a `subject_token`, and a `subject_token_type` parameter. For impersonation use cases, the request can also include `actor_token` and `actor_token_type` parameters. The request might also contain `resource`, `audience`, `scope`, and `requested_token_type` parameters. The optional `resource` parameter identifies an Access Token Management (ATM) instance or a token generator instance. For most use cases, use an ATM instance. Use token generator instances for advanced scenarios. The optional `audience` parameter identifies another client that will use the new token to get access to a resource. If a request includes an `audience` parameter, the AS selects the ATM instance specified in the audience client's configuration as described in the internal processing steps. A successful token exchange ends when the AS sends the client a response containing the requested token. The response also contains `issued_token_type` and `token_type` parameters. To function as the AS, PingFederate requires at least one Token Exchange Processor Policy (TEPP) to use the token exchange grant type. Learn more in [Defining token exchange processor policies](../administrators_reference_guide/pf_defining_token_exchange_processor_policies.html). A TEPP includes a map of subject token types, and optionally actor token types, to token processor instances and a map of attributes from the request and other sources to a TEPP attribute contract. You must assign a default TEPP to the OAuth server. Optionally, you can assign a TEPP to OAuth clients that need to exchange tokens. ## Example use case In this scenario, a user or mobile application calls an API gateway using an existing external access token. The API gateway must then call an internal microservice to complete the request, but the internal microservice requires a different token. The API gateway acts as the OAuth client for the token exchange and sends a token exchange request to the PingFederate AS. PingFederate returns a new token that the API gateway uses to call the internal microservice. ![Sequence diagram showing a token exchange flow between a user or mobile app, an API gateway acting as an OAuth client, PingFederate AS, and an internal microservice resource server.](_images/token-exchange-grant-3-noSP.png)Token exchange flow The following steps outline the end-to-end flow: 1. A user or mobile application calls the API gateway using an existing external access token. 2. The API gateway determines that it must call an internal microservice and that the microservice requires a different token. 3. The API gateway sends a token exchange request to the PingFederate AS containing the token exchange grant type, `subject_token`, and `subject_token_type` parameters. 4. PingFederate processes the request and returns a new token to the API gateway. 5. The API gateway uses the new token to call the internal microservice. 6. The internal microservice validates the token and returns the data. 7. The API gateway returns the resource to the user or mobile application. ## Internal PingFederate processing When PingFederate receives a token exchange request from an OAuth client, it performs the following processing: 1. PingFederate selects the TEPP. If the OAuth client's configuration specifies a TEPP, PingFederate selects that TEPP. Otherwise, PingFederate selects the default OAuth server TEPP. PingFederate then uses the TEPP's map of subject token types, and optionally actor token types, to select a token processor instance, which uses the TEPP's attribute map to produce a TEPP attribute contract. 2. PingFederate selects an ATM instance or token generator instance. For most use cases, use an ATM instance. Use token generator instances for advanced scenarios. If the request does not include an `audience` or `resource` parameter, PingFederate selects the default OAuth server ATM instance. If the request includes `resource` parameters, `audience` parameters, or both, and they identify a single ATM or token generator instance, PingFederate selects it. Otherwise, PingFederate returns an error. 3. The selected ATM or token generator instance uses the attribute contract to generate the token. If the request does not include `requested_token_type`, the default token type is generated. If the request includes `requested_token_type`, that type is generated. If the requested token type is not supported, PingFederate returns an error. 4. PingFederate sends the client a response containing the requested token. | | | | - | ---------------------------------------------------------------------------------------------------------- | | | For impersonation use cases, the request can also include `actor_token` and `actor_token_type` parameters. |