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
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).
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]
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
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
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)
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"
}
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 |
|
403 |
FORBIDDEN |
insufficient_scope |
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"
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"
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"}