> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt) # Introspect API documentation for the FusionAuth Introspect OAuth2 endpoint. # Introspect This is an implementation of the Introspect endpoint as defined by the [RFC 7662](https://tools.ietf.org/html/rfc7662). ## Request Inspect an access token issued by this OAuth provider POST/oauth2/introspect OpenAPI Spec ### Request Headers `Authorization`Stringoptional This header is optional if you have provided the **client\_id** in the request body. The **client\_secret** may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the **client\_secret** must be valid. Please see [the Client Secret section](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. If providing client authentication using the [Basic Authentication Scheme](https://tools.ietf.org/html/rfc7617#section-2) authorization header, the value is created by taking the `clientId` and `clientSecret` properties defined in the Application OAuth Configuration and concatenating them together using a `:` character. Here is an example of these two values concatenated. ```plaintext 463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892 ``` This value is then Base64 encoded and prepended with the string `Basic` to denote the schema type. The following is an example Authorization header using the example concatenation above. ```plaintext Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI= ``` The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different. `Content-Type`Stringrequired This value must be set to `application/x-www-form-urlencoded`. ### Request Parameters Ensure you are sending these parameters as form encoded data in the request body, do not send these parameters in a query string. `client_id`Stringoptional The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate. This parameter is optional when the `Authorization` header is provided. When the `Authorization` header is not provided, this parameter is then required. Prior to version `1.46.0` this parameter was always required. `client_secret`StringoptionalAvailable since 1.46.0 The client secret. This parameter is optional when the `Authorization` header is provided. Please see the [the Client Secret table](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. `token`Stringrequired The access token returned by this OAuth provider as the result of a successful authentication. Starting in version `1.46.0` this endpoint will also accept a token generated by the Client Credentials Grant. `token_type_hint`Stringoptional An optional hint to identify the token type. When this value is omitted, the token can be an `access_token` or `id_token`. When this value is specified, it must match the token type. In order to use a refresh token, this value must be set to `refresh_token`. The possible values are: * `access_token` * `id_token` * `refresh_token` Available since 1.60.0 Example HTTP Request ```plaintext POST /oauth2/introspect HTTP/1.1 Host: piedpiper.fusionauth.io Content-Type: application/x-www-form-urlencoded Accept: */* Content-Length: 436 client_id=3c219e58-ed0e-4b18-ad48-f4f92793ae32&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MTM3MTM3NzIsImlhdCI6MTUxMzcxMDE3MiwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiI3MWMxZjE5Yy1kZTRlLTRiZDEtODc3My0zNThkYmIwNWYxNWEiLCJlbWFpbCI6ImRhbmllbEBpbnZlcnNvZnQuY29tIiwiYXBwbGljYXRpb 25JZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMSIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlBBU1NXT1JEIiwicm9sZXMiOltdfQ.KxfM37hlw-5mKXOP9bCm7O6qdQdleT4gJmudhFueiJA ``` ## Response *Response Codes* | Code | Description | | --- | --- | | 200 | The request was successful. | | 400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the [OAuth Error section](https://fusionauth.io/docs/apis/oauth/oauth-error.md) of the API documentation. | | 401 | The token provided in the request was not issued for the `client_id` provided on the request. | | 500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. | | 503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. | ### Response Body This is an example response body when the provided `access_token` was issued on behalf of a user using the Authorization Code Grant, Implicit Grant, Password Credentials Grant or Refresh Token Grant. `active`String When this value is `true` the token is valid and additional claims will be provided in the response body. When this value is `false` no claims will be provided in the response body. `applicationId`UUID The unique Id of the Application for which the user has been authenticated. This claim is only present if the user is registered for the application. `aud`String The `client_id` that was used to request the access token. Available since 1.67.0 When the application has a non-empty **oauthConfiguration.authorizedResourceUris** and a `resource` parameter was resolved during the OAuth flow, this value changes from a plain string to an array. The first element is always the `client_id` followed by each resolved resource URI: `["client_id", "https://resource1.example.com", ...]`. `auth_time`Long The time of the initial authentication request, expressed as [unix time](https://fusionauth.io/docs/reference/data-types.md#unix-time). The value will not change even if the token is re-issued using a Refresh Token. `authenticationType`String The method used to authenticate the user that resulted in the generated JWT. The possible values are: * `APPLE` - The user was authenticated using Apple. Available since 1.17.0 * `APPLICATION_TOKEN` - The user was authenticated using an [Application Authentication Token](https://fusionauth.io/docs/lifecycle/authenticate-users/application-authentication-tokens.md). * `FACEBOOK` - The user was authenticated using Facebook.   Available since 1.1.0 * `FEDERATED_JWT` - The user was authenticated using a JWT from an external Identity Provider. * `GENERIC_CONNECTOR` - The user was authenticated using a generic connector.   Available since 1.18.0 * `GOOGLE` - The user was authenticated using Google. Available since 1.1.0 * `HYPR` - The user was authenticated using HYPR provider. Available since 1.12.0 * `JWT_SSO` - A valid JWT authorized to one Application was exchanged for another JWT authorized to a different Application. * `LDAP_CONNECTOR` - The user was authenticated using an LDAP connector.   Available since 1.18.0 * `LINKEDIN` - The user was authenticated using LinkedIn.   Available since 1.23.0 * `ONE_TIME_PASSWORD` The user was authenticated using a one time password.   Available since 1.5.0 * `OPENID_CONNECT` - The user was authenticated using an external OpenID Connect provider. Available since 1.1.0 * `PASSWORD` - The user was authenticated using a loginId and password combination. * `PASSWORDLESS` - The user was authenticated using a passwordless login link.   Available since 1.5.0 * `PING` - The user was authenticated using a `PUT` request on the Login API. This is used to record a login event without prompting for credentials. * `REGISTRATION` - The user was created using the Registration API.   Available since 1.16.0 * `REFRESH_TOKEN` - The user requested a new JWT using a Refresh Token. * `SAMLv2` - The user was authenticated using an external SAMLv2 provider. Available since 1.6.0 * `TWITTER` - The user was authenticated using Twitter. Available since 1.1.0 * `USER_CREATE` - The user was created using the User API.   Available since 1.16.0 `cnf`ObjectAvailable since 1.63.0 The confirmation claim, which is present for DPoP tokens. The `jkt` field contains the base64url encoding of the JWK SHA-256 Thumbprint of the DPoP public key (in JWK format) to which the access token is bound. `email`String The email address of the user. `email_verified`Boolean The verification status of the **email**. This value is `true` when the email is verified. `exp`Long The expiration instant of the access token, expressed as [unix time](https://fusionauth.io/docs/reference/data-types.md#unix-time). `iat`Long The instant the access token was issued, expressed as [unix time](https://fusionauth.io/docs/reference/data-types.md#unix-time). `iss`String The issuer of the access token. `jti`String The unique identifier of the access token. `phone_number`StringAvailable since 1.50.0 The phone number of the user if available. **user.phoneNumber** or **user.mobilePhone** will be used in this order of precedence. `phone_number_verified`BooleanAvailable since 1.59.0 The verification status of the **phone\_number**. This value is `true` when the phone number is verified. `preferred_username`StringAvailable since 1.5.0 The username of the user whose claims are represented by this JWT. `roles`String The roles assigned to the user in the authenticated Application. `scope`String The scope of the access token. This will only be present if scope was requested during authentication. `sub`UUID The subject of the token. The value is the unique Id of the FusionAuth user. `tid`UUIDAvailable since 1.36.0 The unique Id of the user's tenant. *Example JSON Response for a valid token* ```json { "active": true, "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32", "aud": "3c219e58-ed0e-4b18-ad48-f4f92793ae32", "authenticationType": "PASSWORD", "email": "test0@fusionauth.io", "email_verified": true, "exp": 1487975407000, "iat": 1487971807000, "iss": "acme.com", "phone_number": "+15555551212", "phone_number_verified": true, "roles": [ "admin" ], "sub": "858a4b01-62c8-4c2f-bfa7-6d018833bea7" } ``` *Example JSON Response for an invalid token* ```json { "active": false } ``` *Example JSON Response for a a valid refresh token* ```json { "active": true, "exp": 1487975407000 } ``` ### Response Body version Available Since Version 1.46.0 This is an example response body when the provided `access_token` was issued as the result of the Client Credentials Grant. `active`String When this value is `true` the token is valid and additional claims will be provided in the response body. When this value is `false` no claims will be provided in the response body. `aud`Object The intended audience of this access token. This value may be a string or an array of string values representing one to many intended entities. `cnf`ObjectAvailable since 1.63.0 The confirmation claim, which is present for DPoP tokens. The `jkt` field contains the base64url encoding of the JWK SHA-256 Thumbprint of the DPoP public key (in JWK format) to which the access token is bound. `exp`Long The expiration instant of the access token, expressed as [unix time](https://fusionauth.io/docs/reference/data-types.md#unix-time). `iat`Long The instant the access token was issued, expressed as [unix time](https://fusionauth.io/docs/reference/data-types.md#unix-time). `iss`String The issuer of the access token. `jti`String The unique identifier of the access token. `permissions` The optional permissions requested for this access token. If no permissions were requested, this token represents all permissions allowed by the grant. `sub`UUID The subject of the token. The value is the unique Id of the FusionAuth user. `tid`UUID The unique Id of the user's tenant. *Example JSON Response for an valid token* ```json { "active": true, "aud": "3c219e58-ed0e-4b18-ad48-f4f92793ae32", "exp": 1487975407000, "iat": 1487971807000, "iss": "acme.com", "sub": "858a4b01-62c8-4c2f-bfa7-6d018833bea7" } ``` *Example JSON Response for an invalid token* ```json { "active": false } ```