---
title: /oauth2/idtokeninfo
description: The /oauth2/idtokeninfo endpoint is an AM-specific endpoint.
component: pingam
version: 8.1
page_id: pingam:am-oidc1:rest-api-oidc-idtoken-validation
canonical_url: https://docs.pingidentity.com/pingam/8.1/am-oidc1/rest-api-oidc-idtoken-validation.html
keywords: ["OpenID Connect (OIDC)", "Standards", "Endpoints"]
page_aliases: ["oidc1-guide:rest-api-oidc-idtoken-validation.adoc"]
section_ids:
  supported_parameters: Supported parameters
  token_validation: Token validation
  examples: Examples
  subject_claims: Subject claims
---

# /oauth2/idtokeninfo

The `/oauth2/idtokeninfo` endpoint is an AM-specific endpoint.

Use this endpoint to validate *unencrypted* ID tokens and to retrieve claims in the token.

Specify the realm in the request URL; for example:

```none
https://am.example.com:8443/am/oauth2/realms/root/realms/alpha/idtokeninfo
```

## Supported parameters

The ID token information endpoint supports the following parameters:

| Parameter               | Description                                                                                                      | Required                                                                                        |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `claims`                | Comma-separated list of claims to return from the ID token.                                                      | Yes                                                                                             |
| `client_assertion`      | A signed JSON Web Token (JWT) to use as client credentials.                                                      | Yes, for [JWT profile](../am-oauth2/client-auth-jwt.html) authentication                        |
| `client_assertion_type` | The type of assertion, `client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer`. | Yes, for [JWT profile](../am-oauth2/client-auth-jwt.html) authentication                        |
| `client_id`             | Uniquely identifies the application making the request.                                                          | Yes, when authentication is required (default)                                                  |
| `client_secret`         | The password for a confidential client.                                                                          | Yes, when authenticating with [Form parameters (HTTP POST)](../am-oauth2/client-auth-form.html) |
| `id_token`              | The ID token to validate.                                                                                        | Yes                                                                                             |

By default, the client must authenticate to use the endpoint. Optionally disable this in the OAuth 2.0 provider configuration. In the AM admin UI, go to Realms > *realm name* > Services > OAuth2 Provider > Advanced OpenID Connect and disable Idtokeninfo Endpoint Requires Client Authentication.

## Token validation

AM validates the tokens based on rules in the [OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation) specification. Token validation includes the following steps:

1. Extract the first `aud` (audience) claim from the ID token.

   This step depends on the `client_id` parameter to identify the client and validate the `aud` claim.

2. Extract the `realm` claim, if present, and use it to look up the client profile.

   Validation returns an error if no client profile exists.

3. Verify the signature of the ID token.

   This validation step depends on these client profile settings:

   ID Token Signing Algorithm (default: `RS256`)\
   Public key selector (default: `JWKs_URI`)

4. Verify the following claims:

   `aud` (audience)\
   `exp` (expiration)\
   `iat` (issued at)\
   `iss` (issuer)\
   `nbf` (not before, if set)

This endpoint does not check whether the ID token was revoked with the [/oauth2/connect/endSession](rest-api-oidc-endsession-endpoint.html) endpoint.

## Examples

The following example returns all ID token claims:

```bash
$ curl \
--request POST \
--user myClient:mySecret \
--data 'id_token=id-token' \
"https://am.example.com:8443/am/oauth2/realms/root/realms/alpha/idtokeninfo"
{
  "at_hash": "PZg5xZsIlFtRSfg8MAWhWg",
  "sub": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "auditTrackingId": "2e5c7611-4a61-4001-8739-f714d43e9da2-881454",
  "subname": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "iss": "https://am.example.com:8443/am/oauth2/realms/root/realms/alpha",
  "tokenName": "id_token",
  "given_name": "Babs",
  "sid": "+buKyDp+Fbc0/Rkd0OqsfdKy7ZY0nWvcsEetikX+eTc=",
  "aud": "myClient",
  "c_hash": "FP5Nj162jgycmtEeRjVQ-A",
  "acr": "0",
  "org.forgerock.openidconnect.ops": "gkQOcZ1F3ZFdYPd6TiGIgr6scH0",
  "s_hash": "bKE9UspwyIPg8LsQHkJaiQ",
  "azp": "myClient",
  "auth_time": 1676360741,
  "name": "Babs Jensen",
  "realm": "/alpha",
  "exp": 1676364398,
  "tokenType": "JWTToken",
  "iat": 1676360798,
  "family_name": "Jensen"
}
```

Use the optional `claims` parameter to return specific claims as in the following example:

```bash
$ curl \
--request POST \
--user myClient:mySecret \
--data 'id_token=id-token' \
--data 'claims=sub,exp,realm' \
"https://am.example.com:8443/am/oauth2/idtokeninfo"
{
  "sub": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "exp": 1676364398,
  "realm": "/alpha"
}
```

If you request a claim that does not exist, no error occurs; AM omits the claim from the response.

## Subject claims

The subject claim is in the format `(type!subject)`, where:

* `subject` is the identifier of the user/identity, or the name of the OAuth 2.0/OpenID Connect client that is the subject of the token.

* `type` can be one of the following:

  * `age`. Indicates the *subject* is an OAuth 2.0/OpenID Connect-related user-agent or client. For example, an OAuth 2.0 client, a Remote Consent Service agent, and a Web and Java Agent internal client.

  * `usr`. Indicates the *subject* is a user/identity.

For example, `(usr!bjensen)`, or `(age!myOAuth2Client)`.

The value of the `subname` claim, when provided, matches the value of the *subject* portion of the `sub` claim.