/Docs

Introspect

This is an implementation of the Introspect endpoint as defined by the RFC 7662.

Request#

Inspect an access token issued by this OAuth provider

POST/oauth2/introspect
OpenAPI Spec

Request Headers#

AuthorizationStringoptional

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 for more details. If providing client authentication using the Basic Authentication Scheme 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.

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.

Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI=

The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different.

Content-TypeStringrequired

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_idStringoptional

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_secretStringoptionalAvailable since 1.46.0

The client secret. This parameter is optional when the Authorization header is provided. Please see the the Client Secret table for more details.

tokenStringrequired

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_hintStringoptional

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

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

CodeDescription
200The request was successful.
400The 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 of the API documentation.
401The token provided in the request was not issued for the client_id provided on the request.
500There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.
503The 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.

activeString

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.

applicationIdUUID

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.

audString

The client_id that was used to request the access token.

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_timeLong

The time of the initial authentication request, expressed as unix time. The value will not change even if the token is re-issued using a Refresh Token.

authenticationTypeString

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.
  • 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
cnfObjectAvailable 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.

emailString

The email address of the user.

email_verifiedBoolean

The verification status of the email. This value is true when the email is verified.

expLong

The expiration instant of the access token, expressed as unix time.

iatLong

The instant the access token was issued, expressed as unix time.

issString

The issuer of the access token.

jtiString

The unique identifier of the access token.

phone_numberStringAvailable 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_verifiedBooleanAvailable since 1.59.0

The verification status of the phone_number. This value is true when the phone number is verified.

preferred_usernameStringAvailable since 1.5.0

The username of the user whose claims are represented by this JWT.

rolesString

The roles assigned to the user in the authenticated Application.

scopeString

The scope of the access token. This will only be present if scope was requested during authentication.

subUUID

The subject of the token. The value is the unique Id of the FusionAuth user.

tidUUIDAvailable since 1.36.0

The unique Id of the user's tenant.

Example JSON Response for a valid token

{
  "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

{
  "active": false
}

Example JSON Response for a a valid refresh token

{
  "active": true,
  "exp": 1487975407000
}

Response Body#

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.

activeString

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.

audObject

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.

cnfObjectAvailable 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.

expLong

The expiration instant of the access token, expressed as unix time.

iatLong

The instant the access token was issued, expressed as unix time.

issString

The issuer of the access token.

jtiString

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.

subUUID

The subject of the token. The value is the unique Id of the FusionAuth user.

tidUUID

The unique Id of the user's tenant.

Example JSON Response for an valid token

{
  "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

{
  "active": false
}