---
title: TokenIntrospectionAccessTokenResolver
description: In OAuth2ResourceServerFilter, use the token introspection endpoint, /oauth2/introspect, to resolve access tokens and retrieve metadata about the token. The endpoint typically returns the time until the token expires, the OAuth 2.0 scopes associated with the token, and potentially other information.
component: pinggateway
version: 2026
page_id: pinggateway:reference:TokenIntrospectionAccessTokenResolver
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/TokenIntrospectionAccessTokenResolver.html
revdate: 2025-07-07T16:48:22Z
section_ids:
  TokenIntrospectionAccessTokenResolver-usage: Usage
  TokenIntrospectionAccessTokenResolver-properties: Properties
  TokenIntrospectionAccessTokenResolver-example: Example
  TokenIntrospectionAccessTokenResolver-moreinfo: More information
---

# TokenIntrospectionAccessTokenResolver

In OAuth2ResourceServerFilter, use the token introspection endpoint, `/oauth2/introspect`, to resolve access tokens and retrieve metadata about the token. The endpoint typically returns the time until the token expires, the OAuth 2.0 *scopes* associated with the token, and potentially other information.

The introspection endpoint is defined as a standard method for resolving access tokens, in RFC-7662, [OAuth 2.0 Token Introspection](https://www.rfc-editor.org/rfc/rfc7662).

## Usage

Use this resolver with the `accessTokenResolver` property of OAuth2ResourceServerFilter.

```json
"accessTokenResolver": {
  "type": "TokenIntrospectionAccessTokenResolver",
  "config": {
    "amService": AmService reference,          // Use either "amService"
    "endpoint": configuration expression<url>, // or "endpoint", but not both.
    "providerHandler": Handler reference
  }
}
```

## Properties

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

  The AmService heap object to use for the token introspection endpoint. The endpoint is extrapolated from the `url` property of the AmService.

  When the Authorization Server is AM, use this property to define the token introspection endpoint.

  If `amService` is configured, it takes precedence over `endpoint`.

  See also [AmService](AmService.html).

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

  The URI for the token introspection endpoint. Use `/oauth2/introspect`.

  When the Authorization Server is not AM, use this property to define the token introspection endpoint.

  If `amService` is configured, it takes precedence over `endpoint`.

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

  Invoke this HTTP client handler to send token info requests.

  Provide either the name of a Handler object defined in the heap or an inline Handler configuration object.

  Default: [ForgeRockClientHandler](ForgeRockClientHandler.html)

  If you use the AM token introspection endpoint, this handler can be a `Chain` containing a `HeaderFilter` to add the authorization to the request header, as in the following example:

  ```json
  "providerHandler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "HeaderFilter",
          "config": {
            "messageType": "request",
            "add": {
              "Authorization": [ "Basic ${encodeBase64('<client_id>:<client_secret>')}" ]
            }
          }
        }
      ],
      "handler": "ForgeRockClientHandler"
    }
  }
  ```

## Example

You can find an example route that uses the token introspection endpoint in [Validating PingAM access tokens with introspection](../gateway-guide/oauth2-rs-introspect.html).

## More information

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

[OAuth2ResourceServerFilter](OAuth2ResourceServerFilter.html)