Introspect API

Edit on GitHubView Markdown
On this page

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#

Authorization
  • Type: String
  • Optional

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-Type
  • Type: String
  • Required

This value must be set to application/x-www-form-urlencoded.

Request Body#

Send these fields in the request body as form-encoded data (application/x-www-form-urlencoded). Do not send them in a query string.

client_id
  • Type: String
  • Optional

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
  • Type: String
  • Optional
  • Available 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.

token
  • Type: String
  • Required

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
  • Type: String
  • Optional

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

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 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
  • Type: 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
  • Type: 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
  • Type: 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
  • Type: Long

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.

authenticationType
  • Type: 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.
  • 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
  • Type: Object
  • Available 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
  • Type: String

The email address of the user.

email_verified
  • Type: Boolean

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

exp
  • Type: Long

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

iat
  • Type: Long

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

iss
  • Type: String

The issuer of the access token.

jti
  • Type: String

The unique identifier of the access token.

phone_number
  • Type: String
  • Available 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
  • Type: Boolean
  • Available since 1.59.0

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

preferred_username
  • Type: String
  • Available since 1.5.0

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

roles
  • Type: String

The roles assigned to the user in the authenticated Application.

scope
  • Type: String

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

sub
  • Type: UUID

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

tid
  • Type: UUID
  • Available 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 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
  • Type: 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
  • Type: 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
  • Type: Object
  • Available 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
  • Type: Long

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

iat
  • Type: Long

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

iss
  • Type: String

The issuer of the access token.

jti
  • Type: 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
  • Type: UUID

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

tid
  • Type: UUID

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
}

Related

APIs

Authorize API

API documentation for the FusionAuth Authorize OAuth2 endpoint.

fusionauth apirest apihttp api
APIs

Client Secret Reference

Client Secret reference for FusionAuth OAuth2 endpoints.

fusionauth apirest apihttp api
APIs

Device API

API documentation for the FusionAuth Device OAuth2 endpoint.

fusionauth apirest apihttp api
APIs

JSON Web Key Set (JWKS) API

API documentation for the FusionAuth JSON Web Key Set (JWKS) OAuth2 endpoint.

fusionauth apirest apihttp api