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

# Complete Device Authorization

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

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


## OpenAPI

````yaml https://spec.speakeasy.com/authlete/sdk-workspace/authlete-api-explorer-with-code-samples post /api/{serviceId}/device/complete
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/complete:
    post:
      tags:
        - Device Flow
      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.
      operationId: device_complete_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_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'
      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.complete({
                serviceId: "<id>",
                deviceCompleteRequest: {
                  userCode: "XWWKPBWVXQ",
                  result: "AUTHORIZED",
                  subject: "john",
                },
              });

              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.complete_request(service_id: '<id>',
            device_complete_request:
            Models::Components::DeviceCompleteRequest.new(
              user_code: 'XWWKPBWVXQ',
              result: Models::Components::DeviceCompleteRequestResult::AUTHORIZED,
              subject: 'john'
            ))


            unless res.device_complete_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.Complete(ctx, \"<id>\", components.DeviceCompleteRequest{\n        UserCode: \"XWWKPBWVXQ\",\n        Result: components.DeviceCompleteRequestResultAuthorized,\n        Subject: \"john\",\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    if res.DeviceCompleteResponse != 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/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)
components:
  schemas:
    device_complete_request:
      type: object
      required:
        - userCode
        - result
        - subject
      properties:
        userCode:
          type: string
          description: |
            A user code.
        result:
          type: string
          enum:
            - TRANSACTION_FAILED
            - ACCESS_DENIED
            - AUTHORIZED
          description: >
            The result of the end-user authentication and authorization. One of
            the following. Details are

            described in the description.
        subject:
          type: string
          description: |
            The subject (= unique identifier) of the end-user.
        sub:
          type: string
          description: |
            The value of the sub claim that should be used in the ID token.
        authTime:
          type: integer
          format: int64
          description: >
            The time at which the end-user was authenticated. Its value is the
            number of seconds from `1970-01-01`.
        acr:
          type: string
          description: >
            The reference of the authentication context class which the end-user
            authentication satisfied.
        claims:
          type: string
          description: |
            Additional claims which will be embedded in the ID token.
        properties:
          type: array
          items:
            $ref: '#/components/schemas/property'
          description: |
            The extra properties associated with the access token.
        scopes:
          type: array
          items:
            type: string
          description: >
            Scopes to replace the scopes specified in the original device
            authorization request with.

            When nothing is specified for this parameter, replacement is not
            performed.
        errorDescription:
          type: string
          description: >
            The description of the error. If this optional request parameter is
            given, its value is used as

            the value of the `error_description` property, but it is used only
            when the result is not `AUTHORIZED`.

            To comply with the specification strictly, the description must not
            include characters outside

            the set `%x20-21 / %x23-5B / %x5D-7E`.
        errorUri:
          type: string
          description: >
            The URI of a document which describes the error in detail. This
            corresponds to the `error_uri`

            property in the response to the client.
        idtHeaderParams:
          type: string
          description: |
            JSON that represents additional JWS header parameters for ID tokens.
        consentedClaims:
          type: array
          items:
            type: string
          description: |
            the claims that the user has consented for the client application
            to know.
        jwtAtClaims:
          type: string
          description: >
            Additional claims that are added to the payload part of the JWT
            access token.
        accessTokenDuration:
          type: integer
          format: int64
          description: >
            The duration (in seconds) of the access token that may be issued as
            a result of the Authlete

            API call.


            When this request parameter holds a positive integer, it is used as
            the duration of the access

            token in. In other cases, this request parameter is ignored.
        refreshTokenDuration:
          type: integer
          format: int64
          description: >
            The duration (in seconds) of the refresh token that may be issued as
            a result of the Authlete

            API call.


            When this request parameter holds a positive integer, it is used as
            the duration of the refresh

            token in. In other cases, this request parameter is ignored.
        idTokenAudType:
          type: string
          description: >
            The type of the `aud` claim of the ID token being issued. Valid
            values are as follows.


            | Value | Description |

            | ----- | ----------- |

            | "array" | The type of the aud claim is always an array of strings.
            |

            | "string" | The type of the aud claim is always a single string. |

            | null | The type of the aud claim remains the same as before. |


            This request parameter takes precedence over the `idTokenAudType`
            property of the service.
    device_complete_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:
            - SERVER_ERROR
            - USER_CODE_NOT_EXIST
            - USER_CODE_EXPIRED
            - INVALID_REQUEST
            - SUCCESS
          description: >
            The next action that the authorization server implementation should
            take.
    property:
      type: object
      properties:
        key:
          type: string
          description: The key part.
        value:
          type: string
          description: The value part.
        hidden:
          type: boolean
          description: >
            The flag to indicate whether this property hidden from or visible to
            client applications.

            If `true`, this property is hidden from client applications.
            Otherwise, this property is visible to client applications.
    result:
      type: object
      properties:
        resultCode:
          type: string
          description: The code which represents the result of the API call.
        resultMessage:
          type: string
          description: A short message which explains the result of the API call.
  responses:
    '400':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001201
            resultMessage: '[A001201] /auth/authorization, TLS must be used.'
    '401':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001202
            resultMessage: '[A001202] /auth/authorization, Authorization header is missing.'
    '403':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001215
            resultMessage: >-
              [A001215] /auth/authorization, The client (ID = 26837717140341) is
              locked.
    '500':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001101
            resultMessage: '[A001101] /auth/authorization, Authlete Server error.'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Authenticate every request with a **Service Access Token** or
        **Organization Token**.

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


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


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


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

````