Authlete Grant Management Endpoint API

openapi: 3.2.0
info:
  title: Authlete Grant Management 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: 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
paths:
  /api/{serviceId}/gm:
    post:
      summary: Process Grant Management Request
      description: 'The API is for the implementation of the grant management endpoint which is

        defined in "Grant Management for OAuth 2.0".'
      parameters:
      - in: path
        name: serviceId
        description: A service ID.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/g_m_request'
            example:
              accessToken: eyJhbGciOiJFUzI1NiJ9.eyJleHAiOjE1NTk4MTE3NTAsImlzcyI6IjU3Mjk3NDA4ODY3In0K.csmdholMVcmjqHe59YWgLGNvm7I5Whp4phQCoGxyrlRGMnTgsfxtwyxBgMXQqEPD5q5k9FaEWNk37K8uAtSwrA
              subject: '123457884'
              grantId: '57297408867'
              gmAction: REVOKE
      responses:
        '200':
          description: Grant management completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/g_m_response'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      operationId: grant_m_api
      tags:
      - Grant Management 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:
    g_m_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:
          - OK
          - NO_CONTENT
          - UNAUTHORIZED
          - FORBIDDEN
          - NOT_FOUND
          - CALLER_ERROR
          - AUTHLETE_ERROR
          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.

            '
        dpopNonce:
          type: string
          description: 'Get the expected nonce value for DPoP proof JWT, which should be used

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

            '
    grant_management_action:
      type: string
      description: 'The grant management action of the device authorization request.


        The `grant_management_action` request parameter is defined in

        [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html).

        '
      enum:
      - CREATE
      - QUERY
      - REPLACE
      - REVOKE
      - MERGE
    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.
    g_m_request:
      type: object
      required:
      - token
      properties:
        accessToken:
          type: string
          description: An access token to introspect.
        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.

            '
        gmAction:
          $ref: '#/components/schemas/grant_management_action'
        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.

            '
        dpopNonceRequired:
          type: boolean
          description: 'The flag indicating whether to require the DPoP proof JWT to include the `nonce` claim. Even if

            the service''s `dpopNonceRequired` property is `false`, calling the `/auth/gm` API with this

            `dpopNonceRequired` parameter `true` will force the Authlete API to check whether the DPoP proof

            JWT includes the expected `nonce` value.

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

        '