--- title: "Process Introspection Request" method: POST path: "/api/{serviceId}/auth/introspection" tags: ["Introspection Endpoint"] --- # Process Introspection Request `POST /api/{serviceId}/auth/introspection` This API gathers information about an access token. ## Path parameters - `serviceId` string, required ## Request body - IntrospectionRequest - `token` string, required — An access token to introspect. - `scopes` string[] — 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. - `subject` string — 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. - `clientCertificate` string — Client certificate in PEM format, used to validate binding against access tokens using the TLS client certificate confirmation method. - `dpop` string — `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)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. - `htm` string — 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)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. - `htu` string — 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)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. - `resources` string[] — The resources specified by the `resource` request parameters in the token request. See "Resource Indicators for OAuth 2.0" for details. - `acrValues` string[] — Authentication Context Class Reference values one of which the user authentication performed during the course of issuing the access token must satisfy. - `maxAge` integer — 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. - `requiredComponents` string[] — HTTP Message Components required to be in the signature. If absent, defaults to [ "@method", "@target-uri", "authorization" ]. - `uri` string — The full URL of the userinfo endpoint. - `message` string — The HTTP message body of the request, if present. - `headers` Pair[] — 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. - `key` string — The key part. - `value` string — The value part. - `targetUri` string — The target URI of the resource request, including the query part, if any. - `dpopNonceRequired` boolean — 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. - `requestBodyContained` boolean — 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](https://www.rfc-editor.org/rfc/rfc9421.html)) 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 `200` - IntrospectionResponse - `resultCode` string — The code which represents the result of the API call. - `resultMessage` string — A short message which explains the result of the API call. - `action` 'INTERNAL_SERVER_ERROR' | 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'OK' — The next action that the authorization server implementation should take. - `responseContent` string — The content that the authorization server implementation can use as the value of `WWW-Authenticate` header on errors. - `clientId` integer — The client ID. - `clientIdAlias` string — 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`. - `clientIdAliasUsed` boolean — 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. - `expiresAt` integer — The time at which the access token expires. The value is represented in milliseconds since the Unix epoch (1970-01-01). - `subject` string — The subject who is associated with the access token. The value of this property is `null` if the access token was issued using the flow of [Client Credentials Grant](tools.ietf.org/html/rfc6749#section-4.4). - `scopes` string[] — The scopes covered by the access token. - `existent` boolean — `true` if the access token exists. - `usable` boolean — true` if the access token is usable (= exists and has not expired). - `sufficient` boolean — `true` if the access token exists. - `refreshable` boolean — `true` if the access token can be refreshed using the associated refresh token which had been issued along with the access token. `false` if the refresh token for the access token has expired or the access token has no associated refresh token. - `properties` Property[] — The extra properties associated with the access token. - `key` string — The key part. - `value` string — The value part. - `hidden` boolean — The flag to indicate whether this property hidden from or visible to client applications. If `true`, this property is hidden from client applications. Otherwise, this property is visible to client applications. - `certificateThumbprint` string — The client certificate thumbprint used to validate the access token. - `resources` string[] — The target resources. This represents the resources specified by the `resource` request parameters or by the `resource` property in the request object. See "Resource Indicators for OAuth 2.0" for details. - `accessTokenResources` string[] — The target resources this proeprty holds may be the same as or different from the ones `resource` property holds. - `authorizationDetails` AuthzDetails — 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". - `elements` AuthorizationDetailsElement[] — Elements of this authorization details. - `type` string, required — The type of this element. From _"OAuth 2.0 Rich Authorization Requests"_: _"The type of authorization data as a string. This field MAY define which other elements are allowed in the request. This element is REQUIRED."_ This property is always NOT `null`. - `locations` string[] — The resources and/or resource servers. This property may be `null`. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the location of the resource or resource server. This is typically composed of URIs."_ This property may be `null`. - `actions` string[] — The actions. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of actions to be taken at the resource. The values of the strings are determined by the API being protected."_ This property may be `null`. - `dataTypes` string[] — From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of data being requested from the resource."_ This property may be `null`. - `identifier` string — The identifier of a specific resource. From _"OAuth 2.0 Rich Authorization Requests"_: _"A string identifier indicating a specific resource available at the API."_ This property may be `null`. - `privileges` string[] — The types or levels of privilege. From "OAuth 2.0 Rich Authorization Requests": _"An array of strings representing the types or levels of privilege being requested at the resource."_ This property may be `null`. - `otherFields` string — The RAR request in the JSON format excluding the pre-defined attributes such as `type` and `locations`. The content and semantics are specific to the deployment and the use case implemented. - `serviceAttributes` Pair[] — The attributes of this service that the client application belongs to. - `key` string — The key part. - `value` string — The value part. - `clientAttributes` Pair[] — The attributes of the client. - `key` string — The key part. - `value` string — The value part. - `scopeDetails` Scope[] — The scopes property of this class is a list of scope names. The property does not hold information about scope attributes. This scopeDetails property was newly created to convey information about scope attributes. - `name` string — The name of the scope. - `defaultEntry` boolean — `true` to mark the scope as default. Scopes marked as default are regarded as requested when an authorization request from a client application does not contain scope request parameter. - `description` string — The description about the scope. - `descriptions` TaggedValue[] — The descriptions about this scope in multiple languages. - `tag` string — The language tag part. - `value` string — The value part. - `attributes` Pair[] — The attributes of the scope. - `key` string — The key part. - `value` string — The value part. - `grantId` string — 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](https://openid.net/specs/fapi-grant-management.html) , which is supported by Authlete 2.3 and newer versions. - `grant` Grant - `scopes` GrantScope[] - `scope` string — Space-delimited scopes. - `resource` string[] — List of resource indicators. - `claims` string[] — The claims associated with the Grant. - `authorizationDetails` AuthzDetails — 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". - `elements` AuthorizationDetailsElement[] — Elements of this authorization details. - `type` string, required — The type of this element. From _"OAuth 2.0 Rich Authorization Requests"_: _"The type of authorization data as a string. This field MAY define which other elements are allowed in the request. This element is REQUIRED."_ This property is always NOT `null`. - `locations` string[] — The resources and/or resource servers. This property may be `null`. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the location of the resource or resource server. This is typically composed of URIs."_ This property may be `null`. - `actions` string[] — The actions. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of actions to be taken at the resource. The values of the strings are determined by the API being protected."_ This property may be `null`. - `dataTypes` string[] — From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of data being requested from the resource."_ This property may be `null`. - `identifier` string — The identifier of a specific resource. From _"OAuth 2.0 Rich Authorization Requests"_: _"A string identifier indicating a specific resource available at the API."_ This property may be `null`. - `privileges` string[] — The types or levels of privilege. From "OAuth 2.0 Rich Authorization Requests": _"An array of strings representing the types or levels of privilege being requested at the resource."_ This property may be `null`. - `otherFields` string — The RAR request in the JSON format excluding the pre-defined attributes such as `type` and `locations`. The content and semantics are specific to the deployment and the use case implemented. - `forExternalAttachment` boolean — the flag which indicates whether the access token is for an external attachment. - `consentedClaims` string[] — the claims that the user has consented for the client application to know. - `grantType` 'AUTHORIZATION_CODE' | 'IMPLICIT' | 'PASSWORD' | 'CLIENT_CREDENTIALS' | 'REFRESH_TOKEN' | 'CIBA' | 'DEVICE_CODE' | 'TOKEN_EXCHANGE' | 'JWT_BEARER' | 'PRE_AUTHORIZED_CODE' — The grant type of the access token when the access token was created. - `acr` string — The Authentication Context Class Reference of the user authentication that the authorization server performed during the course of issuing the access token. - `authTime` integer — The time when the user authentication was performed during the course of issuing the access token. - `clientEntityId` string — The entity ID of the client. - `clientEntityIdUsed` boolean — Flag which indicates whether the entity ID of the client was used when the request for the access token was made. - `forCredentialIssuance` boolean — The flag indicating whether the token is for credential issuance. - `cnonce` string — The c_nonce - `cnonceExpiresAt` integer — The time at which the `c_nonce` expires. - `issuableCredentials` string — The credentials that can be obtained by presenting the access token. - `dpopNonce` string — The expected nonce value for DPoP proof JWT, which should be used as the value of the `DPoP-Nonce` HTTP header. - `responseSigningRequired` boolean — The flag indicating whether the HTTP response from the protected resource endpoint must include an HTTP message signature ([RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html)) in compliance with [FAPI 2.0 Message Signing](https://openid.bitbucket.io/fapi/fapi-2_0-message-signing.html). When this response parameter is `true`, the HTTP response from the protected resource endpoint must include the `Signature` and `Signature-Input` HTTP fields. - `metadataDocumentLocation` string, uri — The location of the client's metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. - `metadataDocumentUsed` boolean — Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. ## Other responses - `400` - `401` - `403` - `429` — The request exceeded the request rate permitted for the endpoint. - `500` ## Changes - **2026-08-03** `7ad74ab64749` — 1 info - added the non-success response with the status `429` - **2026-03-18** `ae4d495123d1` — 1 breaking, 6 info - the `scopeDetails/items/` response's property type/format changed from ``/`` to `object`/`` for status `200` - added the optional property `scopeDetails/items/attributes` to the response with the `200` status - added the optional property `scopeDetails/items/defaultEntry` to the response with the `200` status - added the optional property `scopeDetails/items/description` to the response with the `200` status - …3 more - **2026-03-16** `9666f7d1f978` — 2 breaking, 5 warning, 1 info - the response property `scopeDetails/items/` became nullable for the status `200` - the `scopeDetails/items/` response's property type/format changed from `object`/`` to ``/`` for status `200` - removed the optional property `scopeDetails/items/attributes` from the response with the `200` status - removed the optional property `scopeDetails/items/defaultEntry` from the response with the `200` status - …4 more - **2025-12-18** `504771740022` — 2 info - added the optional property `metadataDocumentLocation` to the response with the `200` status - added the optional property `metadataDocumentUsed` to the response with the `200` status [Change history](https://skmtc.dev/authlete/apis/authlete-api/changes/api/:serviceId/auth/introspection/post.md) --- [API](https://skmtc.dev/authlete/apis/authlete-api.md) · [All operations](https://skmtc.dev/authlete/apis/authlete-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/authlete/authlete-api/revisions/7ad74ab64749/schema)