---
title: TokenIntrospectionAccessTokenResolver
description: Configure TokenIntrospectionAccessTokenResolver to resolve OAuth 2.0 access tokens using the token introspection endpoint with OAuth2ResourceServerFilter
component: pinggateway
version: 2024.11
page_id: pinggateway:reference:TokenIntrospectionAccessTokenResolver
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/TokenIntrospectionAccessTokenResolver.html
llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: 2026-06-02T09:47:34Z
superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/TokenIntrospectionAccessTokenResolver.html
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

  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 [Validate 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)