Introspect a Token

Endpoint URL: /{customerId}/login/token/introspect



Description

Returns the current state (active or inactive) of a Hosted Login access or refresh token, as well additional claims associated with that token. To a resource server, a client, or an end user, access tokens and refresh tokens look similar to this:

03v-cgrdpp69hHXXIx56pRLyD98kldDxqEwI59MFCFGVuSkLmmkzgmfwm324Wli

However, after using the /{customerId}/token/introspect endpoint to pass the token to the introspection endpoint, you’ll get back information similar to the following:

{
    "active": true,
    "scope": "address email openid phone profile",
    "client_id": "a39796ab-75tg-po9f-3aa5-7yh22kj03a3",
    "token_type": "Bearer",
    "exp": 1552603442,
    "iat": 1552599842,
    "sub": "2edd2f32-1e49-4bf2-b164-763781761b52",
    "aud": [
        "a39796ab-75tg-po9f-3aa5-7yh22kj03a3",
        "https://documentation.akamai.com"
    ]
}


Request Parameters

Parameter

Type

Required

Description

token

string

Yes

Access token or refresh token to be inspected.


Authentication

RFC 7662 defines the OAuth introspection protocol to allow resource servers to query the authorization server for metadata about presented tokens. As such, the introspection endpoint requires Basic authentication. When configuring authentication, use your OIDC client ID as the username and the OIDC client secret as the password. 

Requiring authentication to introspect a token helps guard against “token fishing,” a process in which a malefactor repeatedly tries to inspect possible token values, hoping to find a value that registers as an active token.


Sample Request (curl)

The following command returns the property values for the token 03v-cgrdpp69hHXXIx56pRLyD98kldDxqEwI59MFCFGVuSkLmmkzgmfwm324Wli:


curl -X POST \
  https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/token/introspect \
  -H 'Authorization: Basic RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6Qj4oBfuplftc7tMbR26eZHwtEqaw9RLMBeIJDvqvqyD4l' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'token=03v-cgrdpp69hHXXIx56pRLyD98kldDxqEwI59MFCFGVuSkLmmkzgmfwm324Wli'


Responses

200 OK

If your call to this endpoint succeeds, and the token is valid, you'll get back claim information like this:

{
    "active": true,
    "scope": "address email openid phone profile",
    "client_id": "a39796ab-75tg-po9f-3aa5-7yh22kj03a3",
    "token_type": "Bearer",
    "exp": 1552603442,
    "iat": 1552599842,
    "sub": "2edd2f32-1e49-4bf2-b164-763781761b52",
    "aud": [
        "a39796ab-75tg-po9f-3aa5-7yh22kj03a3",
        "https://documentation.akamai.com"
         ]
}

If the token is no longer valid (i.e., if the token has expired or has been revoked), you’ll get back the following:

{
    "active": false
}

Note that the return value only indicates that the token is no longer valid; no other information about the token is returned. This is a security measure which prevents malefactors from using expired tokens to query the introspection endpoint for information about how tokens are constructed.