Introspect Endpoint

Clients with an access token delivered by the IdP can call the API to get the status of the token.

Returned token information includes:

  • Active (boolean)

  • Issuance time

  • Expiry time

  • Information about the associated user session (such as subject id, aud, scope or acr)

For further information about the Token Introspection standard, go to https://tools.ietf.org/html/rfc7662

Note:  

  • Only confidential OpenID clients can send requests to this endpoint (public clients are not accepted).

  • Only access tokens are supported (refresh tokens are not supported).

Copy

The endpoint is exposed at the following URL (and can be obtained from the server discovery endpoint):

https://[base-server-url]/{tenant}/authn/introspect [POST]
Method Details
POST

The OpenID client can use a supported authentication method or a valid bearer token in the authorization header.

  • Header parameters:

    • [ Authorization ] – the client authentication credentials (encoded using the registered method, such as HTTP basic authentication) or the bearer access token.

    • Content-Type – must be set to application/x-www-form-urlencoded.

  • Body with form parameters:

    • token – the token for which the client wants to get the status.

  • Success:

    • Code: 200

  • Errors:

    • 400 Bad Request

    • 401 Unauthorized

    • 403 Forbidden

Introspect Request

Copy

With a bearer token

POST https://[base-server-url]/{tenant}/authn/introspect HTTP/1.1Content-Type: application/x-www-form-urlencoded
Authorization: Bearer RTp7HwAAAWi5JYNl1ru5c4TZ2yUBv7+KvGEDRzOm
 
token=TXsO2wAAAWi5KDdicIcZ0lgQH7wsrhhd35zl5Jxg
Copy

With client authentication

POST https://[base-server-url]/{tenant}/authn/introspect HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic c3BsLWFwaTpwYXNzd29yZDAx
 
token=RTp7HwAAAWi8%2FxQzzfindIXVdYDN%2B%2BRYfQWrcrBd

Introspect Response

Supported claims in the response:

  • active (required)

  • iss, aud, sub (for example, by whom, for whom, to whom the token was issued)

  • acr

  • scope

  • iat | nbf + exp (the maximum lifetime and can end sooner due to inactivity timeout)

Copy

When the token is active

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
 
{
    "aud": [
        "spl-api"
    ],
    "sub": "test01",
    "acr": "1",
    "nbf": 1549359073,
    "scope": "openid profile",
    "iss": "https://[base-server-url]/tenant/authn/token",
    "active": true,
    "exp": 1549362673,
    "token_type": "Bearer",
    "iat": 1549359073,
    "client_id": "spl-api"
}
Copy

When a token has expired, timed-out, logged out, does not exist, or is invalid (for example, the authenticator is disabled/deleted)

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
 
{"active":false}

Error Responses

Code Label Possible Errors

401

UNAUTHORIZED
  • invalid_token
  • invalid_client

403

FORBIDDEN

insufficient_scope
Copy

The bearer token is not valid

HTTP/1.1 401 Unauthorized
Content-Type: text/html; charset=UTF-8
WWW-Authenticate: Bearer error="invalid_token", error_description="Invalid access token"
Copy

The bearer token is not authorized (for example, the owner of the token is not an OpenID client)

HTTP/1.1 403 Forbidden
Content-Type: text/html; charset=UTF-8
WWW-Authenticate: Bearer error="insufficient_scope", error_description="Insufficient scope"
Copy

Client authentication error

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=UTF-8
 
{"error_description":"Client authentication failed: Password does not match","error":"invalid_client"}