OAuth 2.0 Introspection Endpoint

This OAuth 2.0 introspection endpoint can be used by an app to get information on an access token.

POST /{tenant}/oauth2/v1/introspect/

Introspect an access token

Request

Name	Values	Description	Required
token	The access token as a string	The access token to verify.	Yes
client_id	The Client ID you obtained from the Apps admin page	The Client ID uniquely identifies your App.	Yes
client_secret	The Client Secret you obtained from the Apps admin page	The Client ID and Client Secret are used to authenticate your App.	Yes if available

POST /{tenant}/oauth2/v1/introspect/ HTTP/1.1
Host: theidentityhub.com
Content-Type: application/x-www-form-urlencoded
client_id=[YOUR_CLIENT_ID]
&client_secret=[YOUR_CLIENT_SECRET]
&token=[ACCESS_TOKEN]

Another option is to use Basic Authentication using the base64 encoded binary representation of clientid:clientsecret

POST /{tenant}/oauth2/v1/introspect/ HTTP/1.1
Host: theidentityhub.com
Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0
Content-Type: application/x-www-form-urlencoded
token=[ACCESS_TOKEN]

Response

If the access token is valid, the response is a json result containing the following info on the access token:

Name	Values	Description
active	true or false	This is a boolean value of whether or not the presented token is currently active.
scope	A space delimited set of scopes	The list of scopes associated with this token.
client_id	The id of the client for who the token was issued.
profile
roles

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
"active": "true",
  "profile": {
    "displayName": "John Doe",
    "emailAddress": "doe@mail.com",
    "givenName": "John",
    "identityId": "5556264304309685609",
    "surname": "Doe"    
...
  },
  "scope": "Read Write",
  "roles": [],
  "client_id": "6822953328218568729"

The following information is always returned by the Introspection endpoint (if available for the user), regardless of the App configuration:

Attribute Name	Description
userName	The Identity Id
userNamePasswordAccountUserName	The user name for the build-in Username/Password Account Provider (if user has such an account)
userNamePasswordAccountUserNameMustBeEmailAddress	true if the username of the Username/Password Account Provider has to be an email address
emailAddress	Email address of the user
emailAddresses	All email addresses of the user
mobilePhone	Mobile phone number of the user
mobilePhoneVerified	true if the mobile phone number was verified
givenName	Given name of the user
givenNames	All given names of the user
surname	Surname of the user
surnames	All surnames of the user
displayName	Display name of the user
identityId	The Identity Id
smallPictures	All small picture URL's of the user
mediumPictures	All medium picture URL's of the user
largePictures	All large picture URL's of the user
lastLogin	Last time (UTC) the user logged in
isArchived	true if the user is archived
disabled	true if the user is disabled
oldIdentityIds	List of merged Identity Id's if the user has merged one or more of his/her user accounts
privatePersonalIdentifier	The Identity Id
emailAddressVerified	true if the email address is verified

Other information is only returned when the information is set as available in the App configuration.

If the access token is invalid, the response is the following result:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
    "error":"invalid_token"
}