> ## 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 Device Authorization Request

> This API parses request parameters of a [device authorization request](https://datatracker.ietf.org/doc/html/rfc8628#section-3.1) and returns necessary data for the authorization server implementation to process the device authorization request further.

<Accordion title="Full description" defaultOpen={false}>
  This API is supposed to be called from the within the implementation of the device authorization
  endpoint of the service. The service implementation should retrieve the value of `action` from the
  response and take the following steps according to the value.

  ## INTERNAL\_SERVER\_ERROR

  When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization
  server implementation was wrong or that an error occurred in Authlete.
  In either case, from a viewpoint of the client application, it is an error on the server side.
  Therefore, the authorization server implementation should generate a response to the client application
  with "500 Internal Server Error"s and `application/json`.
  The value of `responseContent` is a JSON string which describes t he 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 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
  is wrong.
  The authorization server implementation should generate a response to the client application with
  "400 Bad Request" and `application/json`.
  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 400 Bad Request
  Content-Type: application/json
  Cache-Control: no-store
  Pragma: no-cache
  &#123;responseContent&#125;
  ```

  ## UNAUTHORIZED

  When the value of `action` is `UNAUTHORIZED`, it means that client authentication of the device authorization
  request failed.
  The authorization server implementation should generate a response to the client application with
  "401 Unauthorized" and `application/json`.
  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 must generate and return
  to the client application.

  ```
  HTTP/1.1 401 Unauthorized
  WWW-Authenticate: (challenge)
  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 device authorization request from the client
  application is valid.
  The authorization server implementation should generate a response to the client application with
  "200 OK" and `application/json`.
  The `responseContent` is a JSON string which 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.
</Accordion>


## OpenAPI

````yaml https://spec.speakeasy.com/authlete/sdk-workspace/authlete-api-explorer-with-code-samples post /api/{serviceId}/device/authorization
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}/device/authorization:
    post:
      tags:
        - Device Flow
      summary: Process Device Authorization Request
      description: >
        This API parses request parameters of a [device authorization
        request](https://datatracker.ietf.org/doc/html/rfc8628#section-3.1)

        and returns necessary data for the authorization server implementation
        to process the device authorization

        request further.
      operationId: device_authorization_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/device_authorization_request'
            example:
              parameters: client_id=26888344961664&scope=history.read
              clientId: '26888344961664'
              clientSecret: >-
                SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/device_authorization_request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/device_authorization_response'
              example:
                resultCode: A220001
                resultMessage: >-
                  [A220001] The device authorization request was processed
                  successfully.
                action: OK
                clientId: 26888344961664
                clientIdAliasUsed: false
                clientName: My Device Flow Client
                deviceCode: p0qzXeRav8u6lJY9omjzR47KK58VwYN7j8xGUD7sq5I
                expiresIn: 3600
                interval: 0
                responseContent: >-
                  {"user_code":"XWWKPBWVXQ","device_code":"p0qzXeRav8u6lJY9omjzR47KK58VwYN7j8xGUD7sq5I","verification_uri_complete":"https://my-service.com/df/verification?XWWKPBWVXQ","verification_uri":"https://my-service.com/df/verification","expires_in":3600}
                scopes:
                  - defaultEntry: false
                    name: history.read
                serviceAttributes:
                  - key: attribute1-key
                    value: attribute1-value
                  - key: attribute2-key
                    value: attribute2-value
                userCode: XWWKPBWVXQ
                verificationUri: https://my-service.com/df/verification
                verificationUriComplete: https://my-service.com/df/verification?XWWKPBWVXQ
          links:
            device_verify:
              $ref: '#/components/links/device_verification'
            device_poll_token:
              $ref: '#/components/links/device_complete'
        '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.deviceFlow.authorization({
                serviceId: "<id>",
                deviceAuthorizationRequest: {
                  parameters: "client_id=26888344961664&scope=history.read",
                  clientId: "26888344961664",
                  clientSecret: "SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog",
                },
              });

              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.device_flow.authorization(service_id: '<id>',
            device_authorization_request:
            Models::Components::DeviceAuthorizationRequest.new(
              parameters: 'client_id=26888344961664&scope=history.read',
              client_id: '26888344961664',
              client_secret: 'SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog'
            ))


            unless res.device_authorization_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.DeviceFlow.Authorization(ctx, \"<id>\", components.DeviceAuthorizationRequest{\n        Parameters: \"client_id=26888344961664&scope=history.read\",\n        ClientID: authlete.Pointer(\"26888344961664\"),\n        ClientSecret: authlete.Pointer(\"SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog\"),\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    if res.DeviceAuthorizationResponse != nil {\n        // handle response\n    }\n}"
      x-code-samples:
        - lang: shell
          label: curl
          source: >
            curl -v -X POST
            https://us.authlete.com/api/21653835348762/device/authorization \

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

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

            -d '{ "parameters": "client_id=26888344961664&scope=history.read",
            "clientId": "26888344961664",
            "clientSecret":"SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog"
            }'
        - lang: java
          label: java
          source: >
            AuthleteConfiguration conf = ...;

            AuthleteApi api = AuthleteApiFactory.create(conf);


            DeviceAuthorizationRequest req = new DeviceAuthorizationRequest();

            req.setParameters(...);

            req.setClientId("26888344961664");

            req.setClientSecret("SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog");


            api.deviceAuthorization(req);
        - lang: python
          source: >
            conf = ...

            api = AuthleteApiImpl(conf)


            req = DeviceAuthorizationRequest()

            req.parameters = ...

            req.clientId = '26888344961664'

            req.clientSecret =
            'SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog'


            api.deviceAuthorization(req)
components:
  schemas:
    device_authorization_request:
      type: object
      required:
        - parameters
      properties:
        parameters:
          type: string
          description: >
            Parameters of a device authorization request which are the request
            parameters that the device

            authorization endpoint 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 device
            authorization request from the

            client application.


            If the device authorization 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 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
            device authorization request from

            the client application.


            If the device authorization 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 device

            authorization endpoint of the authorization server.
        clientCertificatePath:
          type: array
          items:
            type: string
          description: >
            The client certificate path presented by the client during client
            authentication. Each element

            is a string in PEM format.
        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/).
        cimdOptions:
          $ref: '#/components/schemas/cimd_options'
          description: >
            Options for [OAuth Client ID Metadata
            Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)
            (CIMD).


            These options allow per-request control over CIMD behavior, taking
            precedence over service-level configuration when provided.
    device_authorization_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
            - 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.
        clientId:
          type: integer
          format: int64
          description: >
            The client ID of the client application that has made the device
            authorization request.
        clientIdAlias:
          type: string
          description: >
            The client ID alias of the client application that has made the
            device authorization

            request.
        clientIdAliasUsed:
          type: boolean
          description: >
            `true` if the value of the client_id request parameter included in
            the device authorization

            request is the client ID alias. `false` if the value is the original
            numeric client ID.
        clientName:
          type: string
          description: >
            The name of the client application which has made the device
            authorization request.
        clientAuthMethod:
          type: string
          description: >
            The client authentication method that should be performed at the
            device authorization

            endpoint.
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/scope'
          description: |
            The scopes requested by the device authorization request.
          x-mint:
            metadata:
              description: The scopes requested by the device authorization request.
            content: >
              <Accordion title="Full description" defaultOpen={false}>

              Basically, this property holds the value of the scope request
              parameter in the device

              authorization request. However, because unregistered scopes are
              dropped on Authlete

              side, if the `scope` request parameter contains unknown scopes,
              the list returned by

              this property becomes different from the value of the `scope`
              request parameter.


              Note that `description` property and `descriptions` property of
              each scope object in the

              array contained in this property is always `null` even if
              descriptions of the scopes

              are registered.

              </Accordion>
        claimNames:
          type: array
          items:
            type: string
          description: >
            The names of the claims which were requested indirectly via some
            special scopes.

            See [5.4. Requesting Claims using Scope
            Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims)

            in OpenID Connect Core 1.0 for details.
        acrs:
          type: array
          items:
            type: string
          description: >
            The list of ACR values requested by the device authorization
            request.


            Basically, this property holds the value of the `acr_values` request
            parameter in the

            device authorization request. However, because unsupported ACR
            values are dropped

            on Authlete side, if the `acr_values` request parameter contains
            unrecognized ACR values,

            the list returned by this property becomes different from the value
            of the `acr_values`

            request parameter.
        deviceCode:
          type: string
          description: >
            The device verification code. This corresponds to the `device_code`
            property in the

            response to the client.
        userCode:
          type: string
          description: >
            The end-user verification code. This corresponds to the `user_code`
            property in the

            response to the client.
        verificationUri:
          type: string
          description: >
            The end-user verification URI. This corresponds to the
            `verification_uri` property in

            the response to the client.
        verificationUriComplete:
          type: string
          description: >
            The end-user verification URI that includes the end-user
            verification code. This corresponds

            to the `verification_uri_complete` property in the response to the
            client.
        expiresIn:
          type: integer
          format: int32
          description: >
            The duration of the device verification code in seconds. This
            corresponds to the `expires_in`

            property in the response to the client.
        interval:
          type: integer
          format: int32
          description: >
            The minimum amount of time in seconds that the client must wait for
            between polling

            requests to the token endpoint. This corresponds to the `interval`
            property in the response

            to the client.
        warnings:
          type: array
          items:
            type: string
          description: >
            The warnings raised during processing the backchannel authentication
            request.
        resources:
          type: array
          items:
            type: string
          description: >
            The resources specified by the `resource` request parameters. See
            "Resource Indicators

            for OAuth 2.0" for details.
        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.
        dynamicScopes:
          type: array
          items:
            $ref: '#/components/schemas/dynamic_scope'
          description: >
            The dynamic scopes which the client application requested by the
            scope request parameter.
        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.
        grant:
          $ref: '#/components/schemas/grant'
        grantSubject:
          type: string
          description: >
            The subject identifying the user who has given the grant identified

            by the `grant_id` request parameter of the device authorization

            request.

            Authlete 2.3 and newer versions support [Grant Management

            for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html).
            An authorization request may contain a `grant_id`

            request parameter which is defined in the specification. If the
            value of

            the request parameter is valid, &#123;@link #getGrantSubject()&#125;
            will return

            the subject of the user who has given the grant to the client
            application.

            Authorization server implementations may use the value returned from

            &#123;@link #getGrantSubject()&#125; in order to determine the user
            to authenticate.

            The user your system will authenticate during the authorization
            process

            (or has already authenticated) may be different from the user of the

            grant. The first implementer's draft of "Grant Management for OAuth
            2.0"

            does not mention anything about the case, so the behavior in the
            case is

            left to implementations. Authlete will not perform the grant
            management

            action when the `subject` passed to Authlete does not match the

            user of the grant.
        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.
        metadataDocumentLocation:
          type: string
          format: uri
          description: >
            The location of the client's metadata document that was used to
            resolve client metadata.


            This property is set when client metadata was retrieved via the
            [OAuth Client ID Metadata
            Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)
            (CIMD) mechanism.
        metadataDocumentUsed:
          type: boolean
          description: >
            Flag indicating whether a metadata document was used to resolve
            client metadata for this request.


            When `true`, the client metadata was retrieved via the CIMD
            mechanism rather than from the Authlete database.
    cimd_options:
      type: object
      description: >
        Options for [OAuth Client ID Metadata
        Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)
        (CIMD).


        These options allow per-request control over CIMD behavior, taking
        precedence over service-level configuration when provided.
      properties:
        alwaysRetrieved:
          type: boolean
          description: >
            Whether to always retrieve client metadata in the CIMD context
            regardless of the cache's validity.


            Under normal circumstances, client metadata retrieved from the
            location referenced by the client ID is stored in the database with
            an expiration time calculated using HTTP caching mechanisms (see
            [RFC 9111 HTTP
            Caching](https://www.rfc-editor.org/rfc/rfc9111.html)). Until that
            expiration time is reached, Authlete does not attempt to retrieve
            the client metadata again.


            When this flag is set to `true`, Authlete retrieves the client
            metadata regardless of the cache's validity.


            If this flag is included in an Authlete API call and its value is
            `true`, it takes precedence over the corresponding service
            configuration (see `Service.cimdAlwaysRetrieved`).


            This flag is effective only when the service supports CIMD (see
            `Service.clientIdMetadataDocumentSupported`) and CIMD is actually
            used to resolve client metadata. For example, if the client ID in a
            request does not appear to be a valid URI, CIMD will not be used
            even if the service is configured to support it. In such cases, this
            flag has no effect.


            Client metadata retrieval is performed only in the initiating
            request of an authorization flow, and not in any subsequent
            requests. For example, in the authorization code flow, metadata may
            be retrieved during the authorization request, but not during the
            subsequent token request. In contrast, in the client credentials
            flow, metadata retrieval may occur because the token request itself
            is the initiating request in the flow.
        httpPermitted:
          type: boolean
          description: >
            Whether to allow the `http` scheme in client IDs in the CIMD
            context.


            The specification requires the `https` scheme, but if this flag is
            set to `true`, Authlete also allows the `http` scheme. The main
            purpose of this option is to make development easier for developers
            who run CIMD-enabled servers and a web server publishing client
            metadata on their local machines without TLS.


            Given this purpose, it is not recommended to enable this option in
            production environments unless an allowlist is used (see
            `Service.cimdAllowlistEnabled`).


            If this flag is included in an Authlete API call and its value is
            `true`, it takes precedence over the corresponding service
            configuration (see `Service.cimdHttpPermitted`).
        queryPermitted:
          type: boolean
          description: >
            Whether to allow a query component in client IDs in the CIMD
            context.


            Although the specification states that a client ID "SHOULD NOT
            include a query string component," it does technically allow it.
            However, query components are prone to misuse. Therefore, Authlete
            does not allow them by default. Setting this flag to `true` relaxes
            that restriction.


            If this flag is included in an Authlete API call and its value is
            `true`, it takes precedence over the corresponding service
            configuration (see `Service.cimdQueryPermitted`).
    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'
    authz_details:
      type: object
      description: >
        The authorization details. This represents the value of the
        `authorization_details`

        request parameter in the preceding device authorization request which is
        defined in

        "OAuth 2.0 Rich Authorization Requests".
      properties:
        elements:
          type: array
          items:
            $ref: '#/components/schemas/authorization_details_element'
          description: |
            Elements of this authorization details.
    pair:
      type: object
      properties:
        key:
          type: string
          description: The key part.
        value:
          type: string
          description: The value part.
    dynamic_scope:
      type: object
      properties:
        name:
          type: string
          description: The scope name.
        value:
          type: string
          description: The scope value.
    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
    grant:
      type: object
      properties:
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/grant_scope'
        claims:
          type: array
          items:
            type: string
          description: |
            The claims associated with the Grant.
        authorizationDetails:
          $ref: '#/components/schemas/authz_details'
    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.
    tagged_value:
      type: object
      properties:
        tag:
          type: string
          description: The language tag part.
        value:
          type: string
          description: The value part.
    authorization_details_element:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: >
            The type of this element.


            From _"OAuth 2.0 Rich Authorization Requests"_: _"The type of
            authorization data as a string.

            This field MAY define which other elements are allowed in the
            request. This element is REQUIRED."_


            This property is always NOT `null`.
        locations:
          type: array
          items:
            type: string
          description: >
            The resources and/or resource servers. This property may be `null`.


            From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of
            strings representing the location of

            the resource or resource server. This is typically composed of
            URIs."_


            This property may be `null`.
        actions:
          type: array
          items:
            type: string
          description: >
            The actions.


            From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of
            strings representing the kinds of actions

            to be taken at the resource. The values of the strings are
            determined by the API being protected."_


            This property may be `null`.
        dataTypes:
          type: array
          items:
            type: string
          description: >
            From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of
            strings representing the kinds of data being requested

            from the resource."_


            This property may be `null`.
        identifier:
          type: string
          description: >
            The identifier of a specific resource.

            From _"OAuth 2.0 Rich Authorization Requests"_: _"A string
            identifier indicating a specific resource available at the API."_


            This property may be `null`.
        privileges:
          type: array
          items:
            type: string
          description: >
            The types or levels of privilege.

            From "OAuth 2.0 Rich Authorization Requests": _"An array of strings
            representing the types or

            levels of privilege being requested at the resource."_


            This property may be `null`.
        otherFields:
          type: string
          description: >
            The RAR request in the JSON format excluding the pre-defined
            attributes such as `type` and `locations`.

            The content and semantics are specific to the deployment and the use
            case implemented.
    grant_scope:
      type: object
      properties:
        scope:
          type: string
          description: |
            Space-delimited scopes.
        resource:
          type: array
          items:
            type: string
          description: |
            List of resource indicators.
  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.

````