Authlete Device Flow API

openapi: 3.2.0
info:
  title: Authlete Device Flow 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: Device Flow
  description: API endpoints for implementing OAuth 2.0 Device Flow
  x-tag-expanded: false
paths:
  /api/{serviceId}/device/authorization:
    post:
      summary: Process Device Authorization Request
      description: 'This API parses request parameters of a device authorization request

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

        request further.'
      x-mint:
        metadata:
          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.
        content: '<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>

          '
      parameters:
      - in: path
        name: serviceId
        description: A service ID.
        required: true
        schema:
          type: string
      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'
      operationId: device_authorization_api
      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)

          '
      tags:
      - Device Flow
  /api/{serviceId}/device/verification:
    post:
      summary: Process Device Verification Request
      description: The API returns information associated with a user code.
      x-mint:
        metadata:
          description: The API returns information associated with a user code.
        content: '<Accordion title="Full description" defaultOpen={false}>

          After receiving a response from the device authorization endpoint of the authorization server,

          the client application shows the end-user the user code and the verification URI which are included

          in the device authorization response. Then, the end-user will access the verification URI using

          a web browser on another device (typically, a smart phone). In normal implementations, the verification

          endpoint will return an HTML page with an input form where the end-user inputs a user code. The

          authorization server will receive a user code from the form.

          After receiving a user code, the authorization server should call Authlete''s `/device/verification`

          API with the user code. And then, the authorization server implementation should retrieve the value

          of `action` parameter from the API response and take the following steps according to the value.


          ## SERVER_ERROR


          When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The

          authorization server implementation should tell the end-user that something wrong happened and

          urge her to re-initiate a device flow.


          ## NOT_EXIST


          When the value of `action` is `NOT_EXIST`, it means that the user code does not exist. The authorization

          server implementation should tell the end-user that the user code is invalid and urge her to retry

          to input a valid user code.


          ## EXPIRED


          When the value of `action` is `EXPIRED`, it means that the user code has expired. The authorization

          server implementation should tell the end-user that the user code has expired and urge her to

          re-initiate a device flow.


          ## VALID


          When the value of `action` is `VALID`, it means that the user code exists, has not expired, and

          belongs to the service. The authorization server implementation should interact with the end-user

          to ask whether she approves or rejects the authorization request from the device.

          </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/device_verification_request'
            example:
              userCode: XWWKPBWVXQ
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/device_verification_request'
      responses:
        '200':
          description: Device verification completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/device_verification_response'
              example:
                resultCode: A224001
                resultMessage: '[A224001] The user code is valid.'
                action: VALID
                clientId: 26888344961664
                clientIdAliasUsed: false
                clientName: My Device Flow Client
                expiresAt: 1642001978000
                scopes:
                - defaultEntry: false
                  name: history.read
                serviceAttributes:
                - key: attribute1-key
                  value: attribute1-value
                - key: attribute2-key
                  value: attribute2-value
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      operationId: device_verification_api
      x-code-samples:
      - lang: shell
        label: curl
        source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/device/verification \

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

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

          -d ''{ "userCode": "XWWKPBWVXQ" }''

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

          AuthleteApi api = AuthleteApiFactory.create(conf);


          DeviceVerificationRequest req = new DeviceVerificationRequest();

          req.setUserCode("XWWKPBWVXQ");


          api.deviceVerification(req);

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

          api = AuthleteApiImpl(conf)


          req = DeviceVerificationRequest()

          req.setUserCode(''XWWKPBWVXQ'')


          api.deviceVerification(req)

          '
      tags:
      - Device Flow
  /api/{serviceId}/device/complete:
    post:
      summary: Complete Device Authorization
      description: 'This API returns information about what action the authorization server should take after it receives

        the result of end-user''s decision about whether the end-user has approved or rejected a client

        application''s request.'
      x-mint:
        metadata:
          description: This API returns information about what action the authorization server should take after it receives the result of end-user's decision about whether the end-user has approved or rejected a client application's request.
        content: '<Accordion title="Full description" defaultOpen={false}>

          In the device flow, an end-user accesses the verification endpoint of the authorization server where

          she interacts with the verification endpoint and inputs a user code. The verification endpoint checks

          if the user code is valid and then asks the end-user whether she approves or rejects the authorization

          request which the user code represents.

          After the authorization server receives the decision of the end-user, it should call Authlete''s

          `/device/complete` API to tell Authlete the decision.

          When the end-user was authenticated and authorization was granted to the client by the end-user,

          the authorization server should call the API with `result=AUTHORIZED`. In this successful case,

          the subject request parameter is mandatory. The API will update the database record so that `/auth/token`

          API can generate an access token later.

          If the `scope` parameter of the device authorization request included the openid scope, an ID token

          is generated. In this case, `sub`, `authTime`, `acr` and `claims` request parameters in the API

          call to `/device/complete` affect the ID token.

          When the authorization server receives the decision of the end-user and it indicates that she has

          rejected to give authorization to the client, the authorization server should call the API with

          `result=ACCESS_DENIED`. In this case, the API will update the database record so that the `/auth/token`

          API can generate an error response later. If `errorDescription` and `errorUri` request parameters

          are given to the `/device/complete` API, they will be used as the values of `error_description`

          and `error_uri` response parameters in the error response from the token endpoint.

          When the authorization server could not get decision from the end-user for some reasons, the authorization

          server should call the API with `result=TRANSACTION_FAILED`. In this error case, the API will behave

          in the same way as in the case of `ACCESS_DENIED`. The only difference is that `expired_token` is

          used as the value of the `error` response parameter instead of `access_denied`.

          After receiving a response from the `/device/complete` API, the implementation of the authorization

          server should retrieve the value of `action` from the response and take the following steps according

          to the value.


          ## SERVER_ERROR


          When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The

          authorization server implementation should tell the end-user that something wrong happened and

          urge her to re-initiate a device flow.


          ## USER_CODE_NOT_EXIST


          When the value of `action` is `USER_CODE_NOT_EXIST`, it means that the user code included in the API

          call does not exist. The authorization server implementation should tell the end-user that the user

          code has been invalidated and urge her to re-initiate a device flow.


          ## USER_CODE_EXPIRED


          When the value of `action` is `USER_CODE_EXPIRED`, it means that the user code included in the API

          call has expired. The authorization server implementation should tell the end-user that the user

          code has expired and urge her to re-initiate a device flow.


          ## INVALID_REQUEST


          When the value of `action` is `INVALID_REQUEST`, it means that the API call is invalid. Probably,

          the authorization server implementation has some bugs.


          ## SUCCESS


          When the value of `action` is `SUCCESS`, it means that the API call has been processed successfully.

          The authorization server should return a successful response to the web browser the end-user is

          using.

          </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/device_complete_request'
            example:
              userCode: XWWKPBWVXQ
              result: AUTHORIZED
              subject: john
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/device_complete_request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/device_complete_response'
              example:
                resultCode: A241001
                resultMessage: '[A241001] The API call was processed successfully.'
                action: SUCCESS
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      operationId: device_complete_api
      x-code-samples:
      - lang: shell
        label: curl
        source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/device/complete \

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

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

          -d ''{ "userCode": "XWWKPBWVXQ", "result": "AUTHORIZED", "subject": "john" }''

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

          AuthleteApi api = AuthleteApiFactory.create(conf);


          DeviceCompleteRequest req = new DeviceCompleteRequest();

          req.setUserCode("XWWKPBWVXQ");

          req.setResult(DeviceCompleteRequest.Result.AUTHORIZED);

          req.setSubject("john");


          api.deviceComplete(req);

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

          api = AuthleteApiImpl(conf)


          req = DeviceCompleteRequest()

          req.setUserCode(''XWWKPBWVXQ'')

          req.setResult(DeviceCompleteResult.AUTHORIZED)

          req.setSubject(''john'')


          api.deviceComplete(req)

          '
      tags:
      - Device Flow
components:
  schemas:
    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`).

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

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

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