Process Introspection Request
This API gathers information about an access token.
Description
This API is supposed to be called from within the implementations of protected resource endpoints
of the authorization server implementation in order to get information about the access token which
was presented by the client application.
In general, a client application accesses a protected resource endpoint of a service with an access
token, and the implementation of the endpoint checks whether the presented access token has enough
privileges (= scopes) to access the protected resource before returning the protected resource to
the client application. To achieve this flow, the endpoint implementation has to know detailed
information about the access token. Authlete /auth/introspection API can be used to get such information.
The response from /auth/introspection API has some parameters. Among them, it is action parameter
that the authorization server implementation should check first because it denotes the next action
that the authorization server implementation should take. According to the value of action, the
authorization server implementation must take the steps described below.
INTERNAL_SERVER_ERROR
When the value of action is INTERNAL\_SERVER\_ERROR, it means that the request from the authorization
server implementation was wrong or that an error occurred in Authlete.
In either case, from the viewpoint of the client application, it is an error on the server side.
Therefore, the service implementation should generate a response to the client application with
HTTP status of “500 Internal Server Error”. Authlete recommends application/json as the content
type although OAuth 2.0 specification does not mention the format of the error response when the
redirect URI is not usable.
The value of responseContent is a string which describes the error in the format of
RFC 6750 (OAuth 2.0 Bearer Token Usage), so if
the protected resource of the service implementation wants to return an error response to the client
application in the way that complies with RFC 6750 (in other words, if accessTokenType configuration
parameter of the service is Bearer), the value of responseContent can be used as the value of
WWW-Authenticate header.
The following is an example response which complies with RFC 6750.
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{responseContent}
BAD_REQUEST
When the value of action is BAD\_REQUEST, it means that the request from the client application
does not contain an access token (= the request from the authorization server implementation to
Authlete does not contain token request parameter).
A response with HTTP status of “400 Bad Request” must be returned to the client application and
the content type must be application/json.
The value of responseContent is a string which describes the error in the format of RFC
6750 (OAuth 2.0 Bearer Token Usage), so if the
protected resource of the service implementation wants to return an error response to the client
application in the way that complies with RFC 6750 (in other words, if accessTokenType configuration
parameter of the service is Bearer), the value of responseContent can be used as the value of
WWW-Authenticate header.
The following is an example response which complies with RFC 6750.
HTTP/1.1 400 Bad Request
WWW-Authenticate: {responseContent}
Cache-Control: no-store
Pragma: no-cache
UNAUTHORIZED
When the value of action is UNAUTHORIZED, it means that the access token does not exist or has
expired.
The value of responseContent is a string which describes the error in the format of RFC
6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation
wants to return an error response to the client application in the way that complies with RFC
6750 (in other words, if accessTokenType configuration
parameter of the service is Bearer), the value of responseContent can be used as the value of
WWW-Authenticate header.
The following is an example response which complies with RFC 6750.
HTTP/1.1 401 Unauthorized
WWW-Authenticate: {responseContent}
Cache-Control: no-store
Pragma: no-cache
FORBIDDEN
When the value of action is FORBIDDEN, it means that the access token does not cover the required
scopes or that the subject associated with the access token is different from the subject contained
in the request.
A response with HTTP status of “400 Bad Request” must be returned to the client application and
the content type must be application/json.
The value of responseContent is a string which describes the error in the format of RFC
6750 (OAuth 2.0 Bearer Token Usage), so if the
protected resource of the service implementation wants to return an error response to the client
application in the way that complies with RFC 6750 (in other words, if accessTokenType configuration
parameter of the service is Bearer), the value of responseContent can be used as the value of
WWW-Authenticate header.
The following is an example response which complies with RFC 6750.
HTTP/1.1 403 Forbidden
WWW-Authenticate: {responseContent}
Cache-Control: no-store
Pragma: no-cache
OK
When the value of action is OK, it means that the access token which the client application
presented is valid (= exists and has not expired).
The implementation of the protected resource endpoint is supposed to return the protected resource
to the client application.
When action is OK, the value of responseContent is "Bearer error=\"invalid\_request\"". This
is the simplest string which can be used as the value of WWW-Authenticate header to indicate
“400 Bad Request”. The implementation of the protected resource endpoint may use this string to
tell the client application that the request was bad (e.g. in case necessary request parameters
for the protected resource endpoint are missing). However, in such a case, the implementation
should generate a more informative error message to help developers of client applications.
The following is an example error response which complies with RFC 6750.
HTTP/1.1 400 Bad Request
WWW-Authenticate: {responseContent}
Cache-Control: no-store
Pragma: no-cache
Basically, The value of responseContent is a string which describes the error in the format of
RFC 6750 (OAuth 2.0 Bearer Token Usage). So, if
the service has selected Bearer as the value of accessTokenType configuration parameter, the
value of responseContent can be used directly as the value of WWW-Authenticate header. However,
if the service has selected another different token type, the service has to generate error messages
for itself.
_JWT-based access token_
Since version 2.1, Authlete provides a feature to issue access tokens in JWT format. This feature
can be enabled by setting a non-null value to the accessTokenSignAlg property of the service
(see the description of the Service class for details). /api/auth/introspection API can accept
access tokens in JWT format. However, note that the API does not return information contained in
a given JWT-based access token but returns information stored in the database record which corresponds
to the given JWT-based access token. Because attributes of the database record can be modified
after the access token is issued (for example, by using /api/auth/token/update API), information
returned by /api/auth/introspection API and information the given JWT-based access token holds
may be different.
Authorizations
Click the Get Token button below to log in with your Authlete account and retrieve an access token for API access.
Path Parameters
A service ID.
Body
An access token to introspect.
A string array listing names of scopes which the caller (= a protected resource endpoint of the
service) requires. When the content type of the request from the service is application/x-www-form-urlencoded,
the format of scopes is a space-separated list of scope names.
If this parameter is a non-empty array and if it contains a scope which is not covered by the
access token,action=FORBIDDEN with error=insufficient_scope is returned from Authlete.
A subject (= a user account managed by the service) whom the caller (= a protected resource endpoint of the service) requires.
If this parameter is not null and if the value does not match the subject who is associated
with the access token, action=FORBIDDEN with error=invalid_request is returned from Authlete.
Client certificate in PEM format, used to validate binding against access tokens using the TLS client certificate confirmation method.
DPoP header presented by the client during the request to the resource server.
The header contains a signed JWT which includes the public key that is paired with the private key used to sign the JWT. See OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP) for details.
HTTP method of the request from the client to the protected resource endpoint. This field is
used to validate the DPoP header.
See OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP) for details.
URL of the protected resource endpoint. This field is used to validate the DPoP header.
See OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP) for details.
The resources specified by the resource request parameters in the token request. See "Resource Indicators for OAuth 2.0" for details.
Authentication Context Class Reference values one of which the user authentication performed during the course of issuing the access token must satisfy.
The maximum authentication age which is the maximum allowable elapsed time since the user authentication was performed during the course of issuing the access token.
HTTP Message Components required to be in the signature. If absent, defaults to [ "@method", "@target-uri", "authorization" ].
The full URL of the userinfo endpoint.
The HTTP message body of the request, if present.
HTTP headers to be included in processing the signature. If this is a signed request, this must include the Signature and Signature-Input headers, as well as any additional headers covered by the signature.
The target URI of the resource request, including the query part, if any.
This parameter is used as the value of the @target-uri derived component for HTTP message signatures
RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI).
Additionally, other derived components such as @authority, @scheme, @path, @query and
@query-param are computed from this parameter.
When this parameter is omitted, the value of the htu parameter is used. The htu parameter
represents the URL of the resource endpoint, which is identical to the target URI of the resource
request as long as the request does not include a query component. Conversely, if the resource
request includes a query component, the value of the htu parameter will not match the target
URI, and in that case, the HTTP message signature verification will fail.
If neither this targetUri parameter nor the htu parameter is specified, the target URI is
considered unavailable. If HTTP message signing requires the target-uri derived component or
other derived components computed based on the target URI, the HTTP message signature verification
will fail.
The flag indicating whether to check if the DPoP proof JWT includes the expected nonce value.
If this request parameter is set to true or if the service's dpopNonceRequired property is
set to true, the /auth/introspection API checks if the DPoP proof JWT includes the expected
nonce value. In this case, the response from the /auth/introspection API will include the
dpopNonce response parameter, which should be used as the value of the DPoP-Nonce HTTP header.
The flag indicating whether the resource request contains a request body.
When the resource request must comply with the HTTP message signing requirements defined in the
FAPI 2.0 Message Signing specification, the "content-digest" component identifier must be included
in the signature base of the HTTP message signature (see RFC 9421 HTTP Message Signatures)
if the resource request contains a request body.
When this requestBodyContained parameter is set to true, Authlete checks whether "content-digest"
is included in the signature base, if the FAPI profile applies to the resource request.
Response
The code which represents the result of the API call.
A short message which explains the result of the API call.
The next action that the authorization server implementation should take.
INTERNAL_SERVER_ERROR, INVALID_CLIENT, BAD_REQUEST, PASSWORD, OK, TOKEN_EXCHANGE, JWT_BEARER The content that the authorization server implementation is to return to the client application.
Its format varies depending on the value of action parameter.
The value of username request parameter in the token request.
The client application must specify username when it uses Resource Owner Password Grant.
In other words, when the value of grant_type request parameter is password, username request parameter must come along.
This parameter has a value only if the value of grant_type request parameter is password and the token request is valid.
The value of password request parameter in the token request.
The client application must specify password when it uses Resource Owner Password Grant.
In other words, when the value of grant_type request parameter is password, password request parameter must come along.
This parameter has a value only if the value of grant_type request parameter is password and the token request is valid.
The ticket which is necessary to call Authlete's /auth/token/fail API or /auth/token/issue API.
This parameter has a value only if the value of grant_type request parameter is password and the token request is valid.
The newly issued access token.
The datetime at which the newly issued access token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01).
The duration of the newly issued access token in seconds.
The newly issued refresh token.
The datetime at which the newly issued refresh token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01).
The duration of the newly issued refresh token in seconds.
The newly issued ID token. Note that an ID token is issued from a token endpoint only when the response_type request parameter
of the authorization request to an authorization endpoint has contained code and the scope request parameter has contained openid.
The grant type of the token request.
The client ID.
The client ID alias when the token request was made. If the client did not have an alias, this parameter is null.
Also, if the token request was invalid and it failed to identify a client, this parameter is null.
The flag which indicates whether the client ID alias was used when the token request was made.
true if the client ID alias was used when the token request was made.
The subject (= resource owner's ID) of the access token.
Even if an access token has been issued by the call of /api/auth/token API, this parameter is null if the flow of the token request was
Client Credentials Flow (grant_type=client_credentials) because it means the access token
is not associated with any specific end-user.
The scopes covered by the access token.
The extra properties associated with the access token.
This parameter is null when no extra property is associated with the issued access token.
The newly issued access token in JWT format. If the authorization server is configured
to issue JWT-based access tokens (= if the service's accessTokenSignAlg value is a
non-null value), a JWT-based access token is issued along with the original random-string
one.
The resources specified by the resource request parameters in the token request.
See "Resource Indicators for OAuth 2.0" for details.
The target resources of the access token being issued. See "Resource Indicators for OAuth 2.0" for details.
The authorization details. This represents the value of the authorization_details
request parameter in the preceding device authorization request which is defined in
"OAuth 2.0 Rich Authorization Requests".
The attributes of this service that the client application belongs to.
The attributes of the client.
The client authentication method that was performed at the token endpoint.
the value of the grant_id request parameter of the device authorization request.
The grant_id request parameter is defined in
Grant Management for OAuth 2.0
, which is supported by Authlete 2.3 and newer versions.
The audiences on the token exchange request
The grant type of the access token when the access token was created.
urn:ietf:params:oauth:token-type:jwt, urn:ietf:params:oauth:token-type:access_token, urn:ietf:params:oauth:token-type:refresh_token, urn:ietf:params:oauth:token-type:id_token, urn:ietf:params:oauth:token-type:saml1, urn:ietf:params:oauth:token-type:saml2, DEVICE_CODE, TOKEN_EXCHANGE, JWT_BEARER The grant type of the access token when the access token was created.
urn:ietf:params:oauth:token-type:jwt, urn:ietf:params:oauth:token-type:access_token, urn:ietf:params:oauth:token-type:refresh_token, urn:ietf:params:oauth:token-type:id_token, urn:ietf:params:oauth:token-type:saml1, urn:ietf:params:oauth:token-type:saml2, DEVICE_CODE, TOKEN_EXCHANGE, JWT_BEARER The grant type of the access token when the access token was created.
urn:ietf:params:oauth:token-type:jwt, urn:ietf:params:oauth:token-type:access_token, urn:ietf:params:oauth:token-type:refresh_token, urn:ietf:params:oauth:token-type:id_token, urn:ietf:params:oauth:token-type:saml1, urn:ietf:params:oauth:token-type:saml2, DEVICE_CODE, TOKEN_EXCHANGE, JWT_BEARER For RFC 7523 JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants
Indicate whether the previous refresh token that had been kept in the database for a short time was used
The entity ID of the client.
Flag which indicates whether the entity ID of the client was used when the request for the access token was made.
Duration of the c_nonce in seconds.
Get the expected nonce value for DPoP proof JWT, which should be used
as the value of the DPoP-Nonce HTTP header.
Get the c_nonce.
Get the time at which the c_nonce expires in milliseconds since
the Unix epoch (1970-01-01).
Get the names of the claims that the authorization request (which resulted in generation of the access token) requested to be embedded in ID tokens.
Scopes associated with the refresh token.
The session ID, which is the ID of the user's authentication session, associated with a newly created access token.
If the response from the /auth/token API contains the deviceSecret parameter, its value should
be used as the value of this deviceSecret request parameter to the /nativesso API. The authorization
server may choose to issue a new device secret; in that case, it is free to generate a new device
secret and specify the new value.
If the response from the /auth/token API does not contain the deviceSecret parameter, or
if its value is invalid, the authorization server must generate a new device secret and specify
it in the deviceSecret parameter to the /nativesso API.
The specified value is used as the value of the device_secret property in the token response.
The authorization server should compute the hash value of the device secret based on its own logic
and specify the computed hash as the value of this deviceSecretHash request parameter to the
/nativesso API.
When the deviceSecretHash parameter is omitted, the implementation of the /nativesso API
generates the device secret hash by computing the SHA-256 hash of the device secret and encoding
it with base64url. Note that this hash computation logic is not a rule defined in the Native SSO
specification; rather, it is Authlete-specific fallback logic used when the deviceSecretHash
parameter is omitted.