Authlete Revocation Endpoint API

openapi: 3.0.3
info:
  title: Authlete Authorization Endpoint Revocation 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: Revocation Endpoint
  description: API endpoint for implementing OAuth 2.0 Revocation Endpoint.
  x-tag-expanded: false
paths:
  /api/{serviceId}/auth/revocation:
    post:
      summary: Process Revocation Request
      description: 'This API revokes access tokens and refresh tokens.

        '
      x-mint:
        metadata:
          description: This API revokes access tokens and refresh tokens.
        content: '<Accordion title="Full description" defaultOpen={false}>

          This API is supposed to be called from within the implementation of the revocation endpoint ([RFC

          7009](tools.ietf.org/html/rfc7009)) of the authorization server implementation in order to revoke

          access tokens and refresh tokens.

          The response from `/auth/revocation` 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.


          ---


          The following illustrates the response which the service implementation should generate and return

          to the client application.

          ```

          HTTP/1.1 500 Internal Server Error

          Content-Type: application/json

          Cache-Control: no-store

          Pragma: no-cache

          &#123;responseContent&#125;

          ```


          ## INVALID_CLIENT


          When the value of `action` is `INVALID_CLIENT`, it means that authentication of the client failed.

          In this case, the HTTP status of the response to the client application is either "400 Bad Request"

          or "401 Unauthorized".     The description about `invalid_client` shown below is an excerpt from [RFC

          6749](https://datatracker.ietf.org/doc/html/rfc6749).


          ---


          Client authentication failed (e.g., unknown client, no client authentication included, or unsupported

          authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code

          to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate

          via the `Authorization` request header field, the authorization server MUST respond with an HTTP

          401 (Unauthorized) status code and include the `WWW-Authenticate` response header field matching

          the authentication scheme used by the client.


          ---


          In either case, the value of `responseContent` is a JSON string which can be used as the entity

          body of the response to the client application.


          ---


          The following illustrates the response which the service implementation should generate and return

          to the client application.


          ```

          HTTP/1.1 400 Bad Request

          Content-Type: application/json

          Cache-Control: no-store

          Pragma: no-cache

          &#123;responseContent&#125;

          ```


          ```

          HTTP/1.1 401 Unauthorized

          WWW-Authenticate: &#123;challenge&#125;

          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

          is invalid.

          The HTTP status of the response returned to the client application must be "400 Bad Request" and

          the content type must be `application/json`. [RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009),

          [2.2.1. Error Respons](https://datatracker.ietf.org/doc/html/rfc7009#section-2.2.1) states "The

          error presentation conforms to the definition in [Section 5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2)

          of [[RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)]."

          The value of `responseContent` is a JSON string which describes the error, so it can be used

          as the entity body of the response.


          ---


          The following illustrates the response which the authorization server implementation should generate

          and return to the client application.


          ```

          HTTP/1.1 400 Bad Request

          Content-Type: application/json

          Cache-Control: no-store

          Pragma: no-cache

          &#123;responseContent&#125;

          ```


          ## OK


          When the value of `action` is `OK`, it means that the request from the client application is valid

          and the presented token has been revoked successfully or if the client submitted an invalid token.

          Note that invalid tokens do not cause an error. See [2.2. Revocation Response](https://datatracker.ietf.org/doc/html/rfc7009#section-2.2) for details.

          The HTTP status of the response returned to the client application must be 200 OK.

          If the original request from the client application contains callback request parameter and its

          value is not empty, the content type should be `application/javascript` and the content should be

          a JavaScript snippet for JSONP.

          The value of `responseContent` is JavaScript snippet if the original request from the client application

          contains callback request parameter and its value is not empty. Otherwise, the value of `responseContent`

          is `null`.

          ```

          HTTP/1.1 200 OK

          Content-Type: application/javascript

          Cache-Control: no-store

          Pragma: no-cache

          &#123;responseContent&#125;

          ```

          </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/revocation_request'
            example:
              parameters: VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token
              clientId: '26478243745571'
              clientSecret: gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/revocation_request'
      responses:
        '200':
          description: Token revoked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/revocation_response'
              example:
                resultCode: A113001
                resultMessage: '[A113001] The token has been revoked successfully.'
                action: OK
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      operationId: auth_revocation_api
      x-code-samples:
      - lang: shell
        label: curl
        source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/auth/revocation \

          -H ''Content-Type:application/json'' \

          -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \

          -d ''{ "parameters": "token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token", "clientId": "26478243745571", "clientSecret": "gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ" }''

          '
      - lang: java
        label: java
        source: 'AuthleteConfiguration conf = ...;

          AuthleteApi api = AuthleteApiFactory.create(conf);


          RevocationRequest req = new RevocationRequest();

          request.setParameters(...);


          api.revocation(req);

          '
      - lang: python
        source: 'conf = ...

          api = AuthleteApiImpl(conf)


          req = RevocationRequest()

          req.parameters = ...


          api.revocation(req)

          '
      tags:
      - Revocation Endpoint
components:
  schemas:
    revocation_request:
      type: object
      required:
      - parameters
      properties:
        parameters:
          type: string
          description: 'OAuth 2.0 token revocation request parameters which are the request parameters that the OAuth 2.0 token revocation endpoint

            ([RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009)) of the authorization server implementation received from the

            client application.


            The value of parameters is the entire entity body (which is formatted in `application/x-www-form-urlencoded`) of the request

            from the client application.

            '
        clientId:
          type: string
          description: 'The client ID extracted from `Authorization` header of the revocation request from the client application.


            If the revocation endpoint of the authorization server implementation supports Basic Authentication

            as a means of client authentication, and the request from the client application contains its client ID in

            `Authorization` header, the value should be extracted and set to this parameter.

            '
        clientSecret:
          type: string
          description: 'The client secret extracted from `Authorization` header of the revocation request from the client application.


            If the revocation endpoint of the authorization server implementation supports basic authentication as a means of

            client authentication, and the request from the client application contained its client secret in `Authorization` header,

            the value should be extracted and set to this parameter.

            '
        clientCertificate:
          type: string
          description: 'The client certificate used in the TLS connection between the client application and the revocation endpoint.

            '
        clientCertificatePath:
          type: array
          items:
            type: string
          description: 'The certificate path presented by the client during client authentication.

            '
        oauthClientAttestation:
          type: string
          description: 'The value of the `OAuth-Client-Attestation` HTTP header, which is defined in the specification

            of [OAuth 2.0 Attestation-Based Client Authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/).

            '
        oauthClientAttestationPop:
          type: string
          description: 'The value of the `OAuth-Client-Attestation-PoP` HTTP header, which is defined in the specification

            of [OAuth 2.0 Attestation-Based Client Authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/).

            '
    revocation_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
          - INVALID_CLIENT
          - BAD_REQUEST
          - OK
          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.

            Its format varies depending on the value of `action` parameter.

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

        '