OAuth Token APIs

The OAuth token APIs include the following two endpoints:

  • /{customer_id}/token/introspect. Used for returning the metadata associated with an access or refresh token.
  • /{customer_id}/token/revoke. Used to invalidate an access or refresh token.

/{customer_id}/token/introspect

Returns the current state (active or inactive) of a Hosted Login access or refresh token, as well as additional claims associated with that token.

This endpoint includes the following methods:

  • POST

POST

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 /{customer_id}/token/introspect endpoint to pass the token to the introspection endpoint, you’ll get back information similar to the following:c
{
    "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"
    ]
}

Introspection is typically performed by resource servers; these servers need to view the token metadata in order to verify such things as whether or not the token has expired, and which OIDC scopes the token is allowed to request. However, administrators can also use this endpoint to inspect any access or refresh token.

Request Parameters

Parameter Type Required Description
token string Yes Access token or refresh token to be inspected.

Authentication

This endpoint requires Basic authentication. When configuring authentication, use your OIDC client ID as the username and the OIDC client secret as the password. Because you must use Basic authentication, this means that you can only introspect tokens associated with a confidential client. You cannot inspect tokens associated with a public client, because public clients do not have client secrets that can be used as the Basic authentication 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

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 RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6Qj4oB
fuplftc7tMbR26eZHwtEqaw9RLMBeIJDvqvqyD4l' \
  -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:c
{
    "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.

/{customer_id}/token/revoke

Revokes previously-issued access and refresh tokens.

This endpoint includes the following methods:

  • POST

Request Parameters

Parameter Type Required Description
token string Yes Access token or refresh token that you want to revoke.
clientId String No To be used only if the token being revoked is associated with a public client. Do not use Basic authentication for tokens associated with a public client; instead, use the clientId parameter and pass the ID of that client as the parameter value. For example:
clientId="fgr58hg6-bh7j-plo9-ccf4-mmjh2kj78fb"

Authentication

This endpoint requires Basic authentication if the token being revoked is associated with a confidential OIDC client. When configuring authentication for a confidential client, use the client ID as the username and the client secret as the password.

You cannot use Basic authentication if the token being revoked is associated with a public client; that’s because public clients don’t have a client secret that can be used as a password. For public clients, pass the client ID as the parameter value for the clientId parameter.

Sample Request (Curl)

The following command revokes the access token 03v-cgrdpp69hHXXIx56pRLyD98kldDxqEwI59MFCFGVuSkLmmkzgmfwm324Wli:
curl -X POST \
  https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/token/revoke \
  -H 'Authorization: Basic RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6Qj4oB
fuplftc7tMbR26eZHwtEqaw9RLMBeIJDvqvqyD4l' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'token=03v-cgrdpp69hHXXIx56pRLyD98kldDxqEwI59MFCFGVuSkLmmkzgmfwm324Wli'

Responses

200 OK

If your call to this endpoint succeeds, you'll get back the following response:
The token was revoked successfully or the token was invalid.

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 that prevents malefactors from using old tokens to query the revocation endpoint for information about how tokens are constructed.