Authlete Introspection Endpoint API
API endpoints for implementing OAuth 2.0 Introspection Endpoint.
OpenAPI Specification
openapi: 3.0.3
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:
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'
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:
type: string
description: 'The grant type of the access token when the access token was created.
'
enum:
- AUTHORIZATION_CODE
- IMPLICIT
- PASSWORD
- CLIENT_CREDENTIALS
- REFRESH_TOKEN
- CIBA
- DEVICE_CODE
- TOKEN_EXCHANGE
- JWT_BEARER
- PRE_AUTHORIZED_CODE
introspection_request:
type: object
required:
- token
properties:
token:
type: string
description: An access token to introspect.
scopes:
type: array
items:
type: string
description: '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:
type: string
description: '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:
type: string
description: 'Client certificate in PEM format, used to validate binding against access tokens using the TLS
client certificate confirmation method.
'
dpop:
type: string
description: '`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:
type: string
description: '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:
type: string
description: '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:
type: array
items:
type: string
description: 'The resources specified by the `resource` request parameters in the token request. See "Resource Indicators for OAuth 2.0" for details.
'
acrValues:
type: array
items:
type: string
description: 'Authentication Context Class Reference values one of which the user authentication performed during the course
of issuing the access token must satisfy.
'
maxAge:
type: integer
format: int64
description: '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:
type: array
items:
type: string
description: 'HTTP Message Components required to be in the signature. If absent, defaults to [ "@method", "@target-uri", "authorization" ].
'
uri:
type: string
description: 'The full URL of the userinfo endpoint.
'
message:
type: string
description: 'The HTTP message body of the request, if present.
'
headers:
type: array
items:
$ref: '#/components/schemas/pair'
description: '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.
'
targetUri:
type: string
description: 'The target URI of the resource request, including the query part, if any.
'
x-mint:
metadata:
description: The target URI of the resource request, including the query part, if any.
content: '<Accordion title="Full description" defaultOpen={false}>
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](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.2.2)).
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 d
# --- 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