Authlete Introspection Endpoint API
API endpoints for implementing OAuth 2.0 Introspection Endpoint.
API endpoints for implementing OAuth 2.0 Introspection Endpoint.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/authlete-introspection-endpoint-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.2.0
info:
title: Authlete Authorization Endpoint Introspection Endpoint API
description: "Welcome to the **Authlete API documentation**. Authlete is an **API-first service** where every aspect of the \nplatform is configurable via API. This documentation will help you authenticate and integrate with Authlete to \nbuild powerful OAuth 2.0 and OpenID Connect servers.\n\nAt a high level, the Authlete API is grouped into two categories:\n\n- **Management APIs**: Enable you to manage services and clients.\n- **Runtime APIs**: Allow you to build your own Authorization Servers or Verifiable Credential (VC) issuers.\n\n## \U0001F310 API Servers\n\nAuthlete is a global service with clusters available in multiple regions across the world:\n\n- \U0001F1FA\U0001F1F8 **US**: `https://us.authlete.com`\n- \U0001F1EF\U0001F1F5 **Japan**: `https://jp.authlete.com`\n- \U0001F1EA\U0001F1FA **Europe**: `https://eu.authlete.com`\n- \U0001F1E7\U0001F1F7 **Brazil**: `https://br.authlete.com`\n\nOur customers can host their data in the region that best meets their requirements.\n\n## \U0001F511 Authentication\n\nAll API endpoints are secured using **Bearer token authentication**. You must include an access token in every request:\n\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n\n### Getting Your Access Token\n\nAuthlete supports two types of access tokens:\n\n**Service Access Token** - Scoped to a single service (authorization server instance)\n\n1. Log in to [Authlete Console](https://console.authlete.com)\n2. Navigate to your service → **Settings** → **Access Tokens**\n3. Click **Create Token** and select permissions (e.g., `service.read`, `client.write`)\n4. Copy the generated token\n\n**Organization Token** - Scoped to your entire organization\n\n1. Log in to [Authlete Console](https://console.authlete.com)\n2. Navigate to **Organization Settings** → **Access Tokens**\n3. Click **Create Token** and select org-level permissions\n4. Copy the generated token\n\n> ⚠️ **Important Note**: Tokens inherit the permissions of the account that creates them. Service tokens can only \n> access their specific service, while organization tokens can access all services within your org.\n\n### Token Security Best Practices\n\n- **Never commit tokens to version control** - Store in environment variables or secure secret managers\n- **Rotate regularly** - Generate new tokens periodically and revoke old ones\n- **Scope appropriately** - Request only the permissions your application needs\n- **Revoke unused tokens** - Delete tokens you're no longer using from the console\n\n### Quick Test\n\nVerify your token works with a simple API call:\n\n```bash\ncurl -X GET https://us.authlete.com/api/service/get/list \\\n -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\n## \U0001F393 Tutorials\n\nIf you're new to Authlete or want to see sample implementations, these resources will help you get started:\n\n- [Getting Started with Authlete](https://www.authlete.com/developers/getting_started/)\n- [From Sign-Up to the First API Request](https://www.authlete.com/developers/tutorial/signup/)\n\n## \U0001F6E0 Contact Us\n\nIf you have any questions or need assistance, our team is here to help:\n\n- [Contact Page](https://www.authlete.com/contact/)\n"
version: 3.0.16
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- description: 🇺🇸 US Cluster
url: https://us.authlete.com
- description: 🇯🇵 Japan Cluster
url: https://jp.authlete.com
- description: 🇪🇺 Europe Cluster
url: https://eu.authlete.com
- description: 🇧🇷 Brazil Cluster
url: https://br.authlete.com
security:
- bearer: []
tags:
- name: Introspection Endpoint
description: API endpoints for implementing OAuth 2.0 Introspection Endpoint.
x-tag-expanded: false
paths:
/api/{serviceId}/auth/introspection:
post:
summary: Process Introspection Request
description: 'This API gathers information about an access token.
'
x-mint:
metadata:
description: This API gathers information about an access token.
content: '<Accordion title="Full description" defaultOpen={false}>
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](https://datatracker.ietf.org/doc/html/rfc6750) (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](https://datatracker.ietf.org/doc/html/rfc6750) (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](https://datatracker.ietf.org/doc/html/rfc6750) (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](https://datatracker.ietf.org/doc/html/rfc6750) (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](https://datatracker.ietf.org/doc/html/rfc6750) (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.
</Accordion>
'
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/introspection_request'
example:
token: VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI
subject: john
scopes:
- history.read
- timeline.read
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/introspection_request'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/introspection_response'
example:
resultCode: A056001
resultMessage: '[A056001] The access token is valid.'
action: OK
clientAttributes:
- key: attribute1-key
value: attribute1-value
- key: attribute2-key
value: attribute2-value
clientId: 26478243745571
clientIdAlias: my-client
clientIdAliasUsed: false
existent: true
expiresAt: 1640416873000
refreshable: true
responseContent: Bearer error="invalid_request"
scopes:
- history.read
- timeline.read
serviceAttributes:
- key: attribute1-key
value: attribute1-value
- key: attribute2-key
value: attribute2-value
subject: john
sufficient: true
usable: true
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: auth_introspection_api
x-code-samples:
- lang: shell
label: curl
source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/auth/introspection \
-H ''Content-Type:application/json'' \
-H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \
-d ''{ "token": "VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI", "scopes": [ "history.read", "timeline.read" ] }''
'
- lang: java
label: java
source: 'AuthleteConfiguration conf = ...;
AuthleteApi api = AuthleteApiFactory.create(conf);
IntrospectionRequest req = new IntrospectionRequest();
req.setToken("VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI");
req.setScopes(new String[] { "history.read", "timeline.read" });
api.introspection(req);
'
- lang: python
source: 'conf = ...
api = AuthleteApiImpl(conf)
req = IntrospectionRequest()
req.token = ''VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI''
req.scopes = [ ''history.read'', ''timeline.read'' ]
api.introspection(req)
'
tags:
- Introspection Endpoint
/api/{serviceId}/auth/introspection/standard:
post:
summary: Process OAuth 2.0 Introspection Request
description: 'This API exists to help your authorization server provide its own introspection API which complies
with [RFC 7662](https://tools.ietf.org/html/rfc7662) (OAuth 2.0 Token Introspection).
'
x-mint:
metadata:
description: This API exists to help your authorization server provide its own introspection API which complies with [RFC 7662](https://tools.ietf.org/html/rfc7662) (OAuth 2.0 Token Introspection).
content: '<Accordion title="Full description" defaultOpen={false}>
This API is supposed to be called from within the implementations of the introspection endpoint
of your service. The authorization server implementation should retrieve the value of `action` from
the response and take the following steps according to the value.
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".
The value of `responseContent` is a JSON string which describes the error, so it can be used
as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) does not mention anything about the response
body of error responses.
---
The following illustrates an example response which the introspection endpoint of the authorization
server implementation generates and returns to the client application.
```
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{responseContent}
```
## BAD_REQUEST
When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
is invalid. This happens when the request from the client did not include the token request parameter.
See "[2.1. Introspection Request](https://datatracker.ietf.org/doc/html/rfc7662#section-2.1)" in
RFC 7662 for details about requirements for introspection requests.
The HTTP status of the response returned to the client application should be "400 Bad Request".
The value of `responseContent` is a JSON string which describes the error, so it can be used
as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662)
does not mention anything about the response body of error responses.
The following illustrates an example response which the introspection endpoint of the authorization
server implementation generates and returns to the client application.
```
HTTP/1.1 400 Bad Request
Content-Type: application/json
{responseContent}
```
## OK
When the value of `action` is `OK`, the request from the client application is valid.
The HTTP status of the response returned to the client application must be "200 OK" and its content
type must be `application/json`.
The value of `responseContent` is a JSON string which complies with the introspection response
defined in "2.2. Introspection Response" in RFC7662.
---
The following illustrates the response which the introspection endpoint of your authorization server
implementation should generate and return to the client application.
```
HTTP/1.1 200 OK
Content-Type: application/json
{responseContent}
```
Note that RFC 7662 says _"To prevent token scanning attacks, **the endpoint MUST also require some
form of authorization to access this endpoint**"_. This means that you have to protect your introspection
endpoint in some way or other. Authlete does not care about how your introspection endpoint is protected.
In most cases, as mentioned in RFC 7662, "401 Unauthorized" is a proper response when an introspection
request does not satisfy authorization requirements imposed by your introspection endpoint.
</Accordion>
'
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/standard_introspection_request'
example:
parameters: token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/standard_introspection_request'
responses:
'200':
description: Token introspection completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/standard_introspection_response'
example:
resultCode: A145001
resultMessage: '[A145001] Introspection was performed successfully (type=access_token, active=true).'
action: OK
responseContent: '{\"sub\":\"john\",\"scope\":\"history.read timeline.read\",\"iss\":\"https://my-service.example.com\",\"active\":true,\"token_type\":\"Bearer\",\"exp\":1640416873,\"client_id\":\"26478243745571\"}'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: auth_introspection_standard_api
x-code-samples:
- lang: shell
label: curl
source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/auth/introspection/standard \
-H "Content-Type:application/json" \
-H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \
-d ''{ "parameters":"token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token" }''
'
- lang: java
label: java
source: 'AuthleteConfiguration conf = ...;
AuthleteApi api = AuthleteApiFactory.create(conf);
StandardIntrospectionRequest req = new StandardIntrospectionRequest();
req.setParameters(...);
api.standardIntrospection(req);
'
- lang: python
source: 'conf = ...
api = AuthleteApiImpl(conf)
req = StandardIntrospectionRequest()
req.parameters = ...
api.standardIntrospection(req)
'
tags:
- Introspection Endpoint
components:
schemas:
authz_details:
type: object
description: '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".
'
properties:
elements:
type: array
items:
$ref: '#/components/schemas/authorization_details_element'
description: 'Elements of this authorization details.
'
grant_scope:
type: object
properties:
scope:
type: string
description: 'Space-delimited scopes.
'
resource:
type: array
items:
type: string
description: 'List of resource indicators.
'
grant:
type: object
properties:
scopes:
type: array
items:
$ref: '#/components/schemas/grant_scope'
claims:
type: array
items:
type: string
description: 'The claims associated with the Grant.
'
authorizationDetails:
$ref: '#/components/schemas/authz_details'
standard_introspection_response:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
action:
type: string
enum:
- INTERNAL_SERVER_ERROR
- BAD_REQUEST
- OK
- JWT
description: The next action that the authorization server implementation should take.
responseContent:
type: string
description: 'The content that the authorization server implementation is to return to the client
application.
'
tagged_value:
type: object
properties:
tag:
type: string
description: The language tag part.
value:
type: string
description: The value part.
scope:
type: object
properties:
name:
type: string
description: The name of the scope.
defaultEntry:
type: boolean
description: '`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:
type: string
description: The description about the scope.
descriptions:
type: array
description: The descriptions about this scope in multiple languages.
items:
$ref: '#/components/schemas/tagged_value'
attributes:
type: array
description: The attributes of the scope.
items:
$ref: '#/components/schemas/pair'
property:
type: object
properties:
key:
type: string
description: The key part.
value:
type: string
description: The value part.
hidden:
type: boolean
description: '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.
'
introspection_response:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
action:
type: string
enum:
- INTERNAL_SERVER_ERROR
- BAD_REQUEST
- UNAUTHORIZED
- FORBIDDEN
- OK
description: The next action that the authorization server implementation should take.
responseContent:
type: string
description: 'The content that the authorization server implementation can use as the value of `WWW-Authenticate` header on errors.
'
clientId:
type: integer
format: int64
description: The client ID.
clientIdAlias:
type: string
description: '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:
type: boolean
description: '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:
type: integer
format: int64
description: 'The time at which the access token expires.
The value is represented in milliseconds since the Unix epoch (1970-01-01).
'
subject:
type: string
description: '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:
type: array
items:
type: string
description: 'The scopes covered by the access token.
'
existent:
type: boolean
description: '`true` if the access token exists.
'
usable:
type: boolean
description: 'true` if the access token is usable (= exists and has not expired).
'
sufficient:
type: boolean
description: '`true` if the access token exists.
'
refreshable:
type: boolean
description: '`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:
type: array
items:
$ref: '#/components/schemas/property'
description: The extra properties associated with the access token.
certificateThumbprint:
type: string
description: 'The client certificate thumbprint used to validate the access token.
'
resources:
type: array
items:
type: string
description: '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:
type: array
items:
type: string
description: 'The target resources this proeprty holds may be the same as or different from the ones `resource` property holds.
'
x-mint:
metadata:
description: The target resources this proeprty holds may be the same as or different from the ones `resource` property holds.
content: '<Accordion title="Full description" defaultOpen={false}>
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/authlete/refs/heads/main/openapi/authlete-introspection-endpoint-api-openapi.yml