> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Process OAuth 2.0 Introspection Request

> 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).

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


## OpenAPI

````yaml https://spec.speakeasy.com/authlete/sdk-workspace/authlete-api-explorer-with-code-samples post /api/{serviceId}/auth/introspection/standard
openapi: 3.0.3
info:
  title: Authlete API
  description: ''
  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: Service Management
    description: >-
      API endpoints for managing services, including creation, update, and
      deletion of services.
    x-tag-expanded: false
  - name: Client Management
    description: >-
      API endpoints for managing OAuth clients, including creation, update, and
      deletion of clients.
    x-tag-expanded: false
  - name: Authorization Endpoint
    description: API endpoints for implementing OAuth 2.0 Authorization Endpoint.
    x-tag-expanded: false
  - name: Pushed Authorization Endpoint
    description: >-
      API endpoints for implementing OAuth 2.0 Pushed Authorization Requests
      (PAR).
    x-tag-expanded: false
  - name: Token Endpoint
    description: API endpoints for implementing OAuth 2.0 Token Endpoint.
    x-tag-expanded: false
  - name: Token Operations
    description: >-
      API endpoints for various token related operations, including creating,
      revoking and deleting access_tokens with specified scopes.
    x-tag-expanded: false
  - name: Introspection Endpoint
    description: API endpoints for implementing OAuth 2.0 Introspection Endpoint.
    x-tag-expanded: false
  - name: Revocation Endpoint
    description: API endpoint for implementing OAuth 2.0 Revocation Endpoint.
    x-tag-expanded: false
  - name: UserInfo Endpoint
    description: API endpoints for implementing OpenID Connect UserInfo Endpoint.
    x-tag-expanded: false
  - name: JWK Set Endpoint
    description: API endpoints for to generate JSON Web Key Set (JWKS) for a service.
    x-tag-expanded: false
  - name: Discovery Endpoint
    description: API endpoints for implementing OpenID Connect Discovery.
    x-tag-expanded: false
  - name: Configuration Endpoint
    description: API endpoint for accessing configuration settings for a service.
    x-tag-expanded: false
  - name: Dynamic Client Registration
    description: API endpoints for implementing OAuth 2.0 Dynamic Client Registration.
    x-tag-expanded: false
  - name: CIBA
    description: >-
      API endpoints for implementing Client-Initiated Backchannel Authentication
      (CIBA).
    x-tag-expanded: false
  - name: Grant Management Endpoint
    description: >-
      API endpoint for implementing OAuth 2.0 grants, including grant management
      actions like updating and revoking grants.
    x-tag-expanded: false
  - name: Jose Object
    description: API endpoints for JOSE objects.
    x-tag-expanded: false
  - name: Device Flow
    description: API endpoints for implementing OAuth 2.0 Device Flow
    x-tag-expanded: false
  - name: Federation Endpoint
    description: API endpoints for implementing OpenID Federation using Authlete.
    x-tag-expanded: false
  - name: Verifiable Credential Issuer
    description: >-
      API endpoints for implementing and running a Verifiable Credential Issuer
      (VCI).
    x-tag-expanded: false
  - name: Hardware Security Key
    description: API endpoints for managing hardware security keys (HSK).
    x-tag-expanded: false
  - name: Utility Endpoints
    description: API endpoints for various utility operations.
    x-tag-expanded: false
  - name: Native SSO
    description: API endpoints for Native SSO
    x-tag-expanded: false
paths:
  /api/{serviceId}/auth/introspection/standard:
    post:
      tags:
        - Introspection Endpoint
      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).
      operationId: auth_introspection_standard_api
      parameters:
        - in: path
          name: serviceId
          description: A service ID.
          schema:
            type: string
          required: true
      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'
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { Authlete } from "@authlete/typescript-sdk";

            const authlete = new Authlete({
              bearer: process.env["AUTHLETE_BEARER"] ?? "",
            });

            async function run() {
              const result = await authlete.introspection.standardProcess({
                serviceId: "<id>",
                standardIntrospectionRequest: {
                  parameters: "token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token",
                },
              });

              console.log(result);
            }

            run();
        - lang: ruby
          label: Ruby (SDK)
          source: >-
            require 'authlete_ruby_sdk'


            Models = ::Authlete::Models

            s = ::Authlete::Client.new(
              bearer: '<YOUR_BEARER_TOKEN_HERE>'
            )

            res = s.introspection.standard_process(service_id: '<id>',
            standard_introspection_request:
            Models::Components::StandardIntrospectionRequest.new(
              parameters: 'token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token'
            ))


            unless res.standard_introspection_response.nil?
              # handle response
            end
        - lang: go
          label: Go (SDK)
          source: "package main\n\nimport(\n\t\"context\"\n\t\"os\"\n\tauthlete \"github.com/authlete/authlete-go-sdk\"\n\t\"github.com/authlete/authlete-go-sdk/models/components\"\n\t\"log\"\n)\n\nfunc main() {\n    ctx := context.Background()\n\n    s := authlete.New(\n        authlete.WithSecurity(os.Getenv(\"AUTHLETE_BEARER\")),\n    )\n\n    res, err := s.Introspection.StandardProcess(ctx, \"<id>\", components.StandardIntrospectionRequest{\n        Parameters: \"token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token\",\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    if res.StandardIntrospectionResponse != nil {\n        // handle response\n    }\n}"
      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)
components:
  schemas:
    standard_introspection_request:
      type: object
      required:
        - parameters
      properties:
        parameters:
          type: string
          description: >
            Request parameters which comply with the introspection request
            defined

            in "[2.1. Introspection
            Request](https://datatracker.ietf.org/doc/html/rfc7662#section-2.1)"
            in

            RFC 7662.


            The implementation of the introspection endpoint of your
            authorization server will receive an

            HTTP POST [[RFC
            7231](https://datatracker.ietf.org/doc/html/rfc7231)] request with
            parameters

            in the `application/x-www-form-urlencoded` format. It is the entity
            body of the request that

            Authlete's  `/api/auth/introspection/standard` API expects as the
            value of `parameters`.
        withHiddenProperties:
          type: boolean
          description: >
            Flag indicating whether to include hidden properties in the output.


            Authlete has a mechanism whereby to associate arbitrary key-value
            pairs with an access token.

            Each key-value pair has a hidden attribute. By default, key-value
            pairs whose hidden attribute

            is set to `true` are not embedded in the standard introspection
            output.


            If the `withHiddenProperties` request parameter is given and its
            value is `true`, `/api/auth/introspection/standard

            API includes all the associated key-value pairs into the output
            regardless of the value of the

            hidden attribute.
        rsUri:
          type: string
          description: >
            The URI of the resource server making the introspection request.


            If the `rsUri` request parameter is given and the token has audience
            values, Authlete checks if

            the value of the `rsUri` request parameter is contained in the
            audience values. If not contained,

            Authlete generates an introspection response with the `active`
            property set to `false`.


            The `rsUri` request parameter is required when the resource server
            requests a JWT introspection

            response, i.e., when the value of the `httpAcceptHeader` request
            parameter is set to `"application/token-introspection+jwt"`.
        httpAcceptHeader:
          type: string
          description: >
            The value of the `HTTP Accept` header in the introspection request.


            If the value of the `httpAcceptHeader` request parameter is
            `"application/token-introspection+jwt"`,

            Authlete generates a JWT introspection response. See "[4. Requesting
            a JWT
            Response](https://www.rfc-editor.org/rfc/rfc9701.html#section-4)"

            of "[RFC 9701: JWT Response for OAuth Token
            Introspection](https://www.rfc-editor.org/rfc/rfc9701.html)"

            for more details.
        introspectionSignAlg:
          type: string
          description: >
            The JWS `alg` algorithm for signing the introspection response. This
            parameter corresponds to

            `introspection_signed_response_alg` defined in "[6. Client
            Metadata](https://www.rfc-editor.org/rfc/rfc9701.html#section-6)"

            of "[RFC 9701: JWT Response for OAuth Token
            Introspection](https://www.rfc-editor.org/rfc/rfc9701.html)".


            The default value is `RS256`.
        introspectionEncryptionAlg:
          type: string
          description: >
            The JWE `alg` algorithm for encrypting the introspection response.
            This parameter corresponds

            to `introspection_encrypted_response_alg` defined in "[6. Client
            Metadata](https://www.rfc-editor.org/rfc/rfc9701.html#section-6)"

            of "[RFC 9701: JWT Response for OAuth Token
            Introspection](https://www.rfc-editor.org/rfc/rfc9701.html)".


            If the `introspectionEncryptionAlg` request parameter is specified,
            Authlete generates a JWT

            introspection response encrypted with the algorithm by this property
            and the algorithm specified by

            the `introspectionEncryptionEnc` request parameter.
        introspectionEncryptionEnc:
          type: string
          description: >
            The JWE `enc` algorithm for encrypting the introspection response.
            This parameter corresponds

            to `introspection_encrypted_response_enc` defined in "[6. Client
            Metadata](https://www.rfc-editor.org/rfc/rfc9701.html#section-6)"

            of "[RFC 9701: JWT Response for OAuth Token
            Introspection](https://www.rfc-editor.org/rfc/rfc9701.html)".


            The default value is `A128CBC_HS256`.
        sharedKeyForSign:
          type: string
          description: >
            The shared key for signing the introspection response with a
            symmetric algorithm.


            The `sharedKeyForSign` request parameter is required when the
            introspection response is requested

            to be signed with a symmetric algorithm.
        sharedKeyForEncryption:
          type: string
          description: >
            The shared key for encrypting the introspection response with a
            symmetric algorithm.


            The `sharedKeyForEncryption` request parameter is required when the
            introspection response is

            requested to be encrypted with a symmetric algorithm.
        publicKeyForEncryption:
          type: string
          description: >
            The public key for signing the introspection response with an
            asymmetric algorithm.


            The `publicKeyForEncryption` request parameter is required when the
            introspection response is

            requested to be encrypted with an asymmetric algorithm.
    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.
    result:
      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.
  responses:
    '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.'
    '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.'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Authenticate every request with a **Service Access Token** or
        **Organization Token**.

        Set the token value in the `Authorization: Bearer <token>` header.


        **Service Access Token**: Scoped to a single service. Use when
        automating service-level configuration or runtime flows.


        **Organization Token**: Scoped to the organization; inherits permissions
        across services. Use for org-wide automation or when managing multiple
        services programmatically.


        Both token types are issued by the Authlete console or provisioning
        APIs.

````