Authlete Introspection Endpoint API

openapi: 3.2.0
info:
  title: Authlete Introspection Endpoint API
  description: Welcome to the **Authlete API documentation**.
  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

          &#123;responseContent&#125;

          ```


          ## 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: &#123;responseContent&#125;

          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: &#123;responseContent&#125;

          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: &#123;responseContent&#125;

          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: &#123;responseContent&#125;

          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 (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

          &#123;responseContent&#125;

          ```


          ## 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

          &#123;responseContent&#125;

          ```


          ## 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

          &#123;responseContent&#125;

          ```

          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:
  responses:
    '403':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001215
            resultMessage: '[A001215] /auth/authorization, The client (ID = 26837717140341) is locked.'
    '500':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001101
            resultMessage: '[A001101] /auth/authorization, Authlete Server error.'
    '400':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001201
            resultMessage: '[A001201] /auth/authorization, TLS must be used.'
    '401':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001202
            resultMessage: '[A001202] /auth/authorization, Authorization header is missing.'
  schemas:
    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.

            '
    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}>

              In some flows, the initial request and the subsequent token request are sent to different endpoints.

              Example flows are the Authorization Code Flow, the Refresh Token Flow, the CIBA Ping Mode, the CIBA Poll Mode and the Device Flow.

              In these flows, not only the initial request but also the subsequent token request can include the `resource` request parameters.

              The purpose of the `resource` request parameters in the token request is to narrow the range of the target resources from the original

              set of target resources requested by the preceding initial request. If narrowing down is performed, the target resources holded by the

              `resource` proeprty and the ones holded by this property are different. This property holds the narrowed set of target resources.


              See "Resource Indicators for OAuth 2.0" for details.

              </Accordion>

              '
        authorizationDetails:
          $ref: '#/components/schemas/authz_details'
        serviceAttributes:
          type: array
          items:
            $ref: '#/components/schemas/pair'
          description: 'The attributes of this service that the client application belongs to.

            '
        clientAttributes:
          type: array
          items:
            $ref: '#/components/schemas/pair'
          description: 'The attributes of the client.

            '
        scopeDetails:
          type: array
          items:
            $ref: '#/components/schemas/scope'
          description: '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.

            '
        grantId:
          type: string
          description: '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:
          $ref: '#/components/schemas/grant'
        forExternalAttachment:
          type: boolean
          description: 'the flag which indicates whether the access token is for an external

            attachment.

            '
        consentedClaims:
          type: array
          items:
            type: string
          description: 'the claims that the user has consented for the client application

            to know.

            '
        grantType:
          $ref: '#/components/schemas/grant_type'
        acr:
          type: string
          description: 'The Authentication Context Class Reference of the user authentication that the authorization server performed

            during the course of issuing the access token.

            '
        authTime:
          type: integer
          format: int64
          description: 'The time when the user authentication was performed during the course of issuing the access token.

            '
        clientEntityId:
          type: string
          description: 'The entity ID of the client.

            '
        clientEntityIdUsed:
          type: boolean
          description: 'Flag which indicates whether the entity ID of the client was used when the request for the access token was made.

            '
        forCredentialIssuance:
          type: boolean
          description: The flag indicating whether the token is for credential issuance.
        cnonce:
          type: string
          description: The c_nonce
        cnonceExpiresAt:
          type: integer
          format: int64
          description: The time at which the `c_nonce` expires.
        issuableCredentials:
          type: string
          description: The credentials that can be obtained by presenting the access token.
        dpopNonce:
          type: string
          description: 'The expected nonce value for DPoP proof JWT, which should be used

            as the value of the `DPoP-Nonce` HTTP header.

            '
        responseSigningRequired:
          type: boolean
          description: '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.

            '
        meta

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/authlete/refs/heads/main/openapi/authlete-introspection-endpoint-api-openapi.yml