OAuth Token APIs

In this article:



/{customerId}/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 /{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.



/{customerId}/token/revoke

Back to top


Revokes previously-issued access and refresh tokens.

This endpoint includes the following methods:

  • POST

POST

Description

Revokes previously-issued access tokens or refresh tokens. After an access token has been revoked, it can no longer be used to gain access to a protected resource. After a refresh token has been revoked, it can no longer be used to request a new access token. 

Note that the client attempting to revoke a token must be the same client that originally issued the token,.

Request Parameters

Note that request parameters must be configured as x-www-form-urlencoded parameters.

Parameter

Type

Required

Description

token

string

Yes

Access token or refresh token that you want to revoke.

client_id

String

No

Should be used only if the OIDC client is a public client; for confidential clients, use Basic authentication instead. Either way, the client trying to revoke the token must be same client that issued the token: OIDC client A can't revoke a token that was issued by OIDC client B.

Authentication

The authentication method employed when revoking a token depends on the type of OIDC client you're using:

  • If you're using a confidential client, use Basic authentication, setting the client ID as the username and the client secret as the password.
     
  • If you're using a public client, pass the client ID as the parameter value for the client_id parameter.

Sample Request for a Confidential Client (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 RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6Qj4oBfuplftc7tMbR26eZHwtEqaw9RLMBeIJDvqvqyD4l' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'token=03v-cgrdpp69hHXXIx56pRLyD98kldDxqEwI59MFCFGVuSkLmmkzgmfwm324Wli'

Sample Request for a Public Client (curl)

The following command revokes the access token 2dbk62MffhrYsSt0MYKYiRw29dEXI4dBfvsLXb6yVeMHppjgfeZ8S5acqzGLVfnO:


curl -X POST \
  https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/token/revoke \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'token=2dbk62MffhrYsSt0MYKYiRw29dEXI4dBfvsLXb6yVeMHppjgfeZ8S5acqzGLVfnO' \
  --data-urlencode 'client_id=70a45721-c6ef-4d7c-91ff-f14e9346b8b6'

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.