---
title: OAuth2TokenExchangeFilter
description: Identifies a client's access token or ID token (a subject token), and communicates with an authorization service, such as AM, to exchange it for a new token (an issued token):
component: pinggateway
version: 2026
page_id: pinggateway:reference:OAuth2TokenExchangeFilter
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/OAuth2TokenExchangeFilter.html
revdate: 2026-01-15
section_ids:
  OAuth2TokenExchangeFilter-usage: Usage
  OAuth2TokenExchangeFilter-conf: Configuration
  OAuth2TokenExchangeFilter-example: Example
  OAuth2TokenExchangeFilter-moreinfo: More information
---

# OAuth2TokenExchangeFilter

Identifies a client's access token or ID token (a *subject token*), and communicates with an authorization service, such as AM, to exchange it for a new token (an *issued token*):

* When the OAuth2TokenExchangeFilter succesfully exchanges a token, it injects the issued token and its scopes into the [OAuth2TokenExchangeContext](OAuth2TokenExchangeContext.html).

* When the OAuth2TokenExchangeFilter fails to exchange a token, it injects information about the failure into the [OAuth2FailureContext](OAuth2FailureContext.html), which is provided to the `failureHandler`.

The scopes for issued token can be *restricted* or *expanded* by the authorization services:

* Restricted when the token scopes are a subset of those available to the subject token.

* Expanded when they have scopes that aren't included in the subject token.

Use this filter in the *impersonation* use case. Learn more in the AM documentation on [Token Exchange](https://docs.pingidentity.com/pingam/8.1/am-oauth2/token-exchange.html).

## Usage

```json
{
  "name": string,
  "type": "OAuth2TokenExchangeFilter",
    "config": {
      "subjectToken": runtime expression<string>,
      "amService": AmService reference,
      "endpoint": configuration expression<url>,
      "subjectTokenType": configuration expression<string>,
      "requestedTokenType": configuration expression<string>,
      "scopes": [ runtime expression<string>, ... ] or ScriptableResourceAccess reference,
      "resource": configuration expression<url>,
      "audience": configuration expression<string>,
      "endpointHandler": Handler reference,
      "failureHandler": Handler reference
  }
}
```

## Configuration

* `"subjectToken"`: *runtime expression<[string](preface.html#definition-string)>, required*

  The location of the subject token in the inbound request.

* `"amService"`: *AmService [reference](preface.html#definition-reference), required if `endpoint` isn't configured*

  The AmService to use as the authorization service.

  Configure either 'amService' or 'endpoint'. If both are configured, 'amService' takes precedence.

* `"endpoint"`: *configuration expression<[url](preface.html#definition-url)>, required if `amService` isn't configured*

  The URI for the authorization service.

  Configure either 'amService' or 'endpoint'. If both are configured, 'amService' takes precedence.

* `"subjectTokenType"`: *configuration expression<[string](preface.html#definition-string)>, optional*

  The subject token type.

  Default: `URN_ACCESS_TOKEN`

* `"requestedTokenType"`: *configuration expression<[string](preface.html#definition-string)>, optional*

  The type of token being requested.

  Default: `URN_ACCESS_TOKEN`

* `"scopes"`: *array of runtime expression<[strings](preface.html#definition-string)> or ResourceAccess <[reference](preface.html#definition-reference)>, required*

  A list of one or more scopes required by the OAuth 2.0 access token. Provide the scopes as strings or through a ResourceAccess such as a ScriptableResourceAccess:

  * Array of runtime expression<[strings](preface.html#definition-string)>, required if a [ResourceAccess](../_attachments/apidocs/org/forgerock/http/oauth2/ResourceAccess.html) isn't used

    A string, array of strings, runtime expression\<string>, or array of runtime expression\<string> to represent one or more scopes.

  - ScriptableResourceAccess <[reference](preface.html#definition-reference)>

    A script that evaluates each request dynamically and returns the scopes that the request needs to access the protected resource. The script must return a `Set<String>`.

    For information about the properties of ScriptableResourceAccess, refer to [PingGateway scripts](Scripts.html).

    ```json
    {
      "name": string,
      "type": "ScriptableResourceAccess",
      "config": {
        "type": configuration expression<string>,
        "file": configuration expression<string>, // Use either "file"
        "source": [ string, ... ],                // or "source", but not both.
        "args": object,
        "clientHandler": Handler reference
      }
    }
    ```

    Default: Empty

* `"resource"`: *configuration expression<[url](preface.html#definition-url)>, optional*

  The target service URI where the issued token is intended to be used.

* `"audience"`: *configuration expression<[url](preface.html#definition-url)>, optional*

  The target service name where the token is intended to be used.

* `"endpointHandler"`: *Handler [reference](preface.html#definition-reference), optional*

  The handler to exchange tokens on the authorization endpoint.

  Configure this property as a [Chain](Chain.html), using one of the following filters for client authentication:

  * [ClientSecretBasicAuthenticationFilter](ClientSecretBasicAuthenticationFilter.html)

  * [ClientSecretPostAuthenticationFilter](ClientSecretPostAuthenticationFilter.html)

  * [EncryptedPrivateKeyJwtClientAuthenticationFilter](EncryptedPrivateKeyJwtClientAuthenticationFilter.html)

  * [PrivateKeyJwtClientAuthenticationFilter](PrivateKeyJwtClientAuthenticationFilter.html)

  ```json
  {
    "name": "EndpointHandler",
    "type": "Chain",
    "config": {
      "handler": "ForgeRockClientHandler",
      "filters": [
        {
          "type": "ClientSecretBasicAuthenticationFilter",
          "config": {
            "clientId": "serviceConfidentialClient",
            "clientSecretId": "client.secret.id",
            "secretsProvider" : "SystemAndEnvSecretStore-1",
          }
        }
      ]
    }
  }
  ```

  Default: [ForgeRockClientHandler](ForgeRockClientHandler.html)

* `"failureHandler"`: *Handler <[reference](preface.html#definition-reference)>, optional*

  Handler to manage a failed request.

  Provide an inline handler configuration object or the name of a handler object declared in the heap. The handler can access information in the [OAuth2FailureContext](OAuth2FailureContext.html).

  Default: `500 Internal Server Error`, the request stops being executed.

## Example

You can find an example of how this filter is used in [OAuth 2.0 token exchange with PingAM](../gateway-guide/token-exchange.html).

## More information

[org.forgerock.http.oauth2.OAuth2TokenExchangeFilter](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/OAuth2TokenExchangeFilter.html)

[OAuth2TokenExchangeContext](OAuth2TokenExchangeContext.html)

[OAuth2FailureContext](OAuth2FailureContext.html)

[The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749)