> ## 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 Verification Request

> The API returns information associated with a user code.

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


## OpenAPI

````yaml https://spec.speakeasy.com/authlete/sdk-workspace/authlete-api-explorer-with-code-samples post /api/{serviceId}/device/verification
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/verification:
    post:
      tags:
        - Device Flow
      summary: Process Device Verification Request
      description: |
        The API returns information associated with a user code.
      operationId: device_verification_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_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'
      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.verification({
                serviceId: "<id>",
                deviceVerificationRequest: {
                  userCode: "XWWKPBWVXQ",
                },
              });

              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.verification(service_id: '<id>',
            device_verification_request:
            Models::Components::DeviceVerificationRequest.new(
              user_code: 'XWWKPBWVXQ'
            ))


            unless res.device_verification_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.Verification(ctx, \"<id>\", components.DeviceVerificationRequest{\n        UserCode: \"XWWKPBWVXQ\",\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    if res.DeviceVerificationResponse != 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/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)
components:
  schemas:
    device_verification_request:
      type: object
      required:
        - userCode
      properties:
        userCode:
          type: string
          description: |
            A user code.
    device_verification_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
            - NOT_EXIST
            - EXPIRED
            - VALID
          description: >-
            The next action that the authorization server implementation should
            take.
        clientId:
          type: integer
          format: int64
          description: >
            The client ID of the client application to which the user code has
            been issued.
        clientIdAlias:
          type: string
          description: >
            The client ID alias of the client application to which the user code
            has been issued.
        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 to which the user code has been
            issued.
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/scope'
          description: >
            The scopes requested by the device authorization request.


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


            This property is always `null` if the `scope` request parameter of
            the device authorization

            request does not include the `openid` scope even if special scopes
            (such as `profile`)

            are included in the request (unless the openid scope is included in
            the default set

            of scopes which is used when the `scope` request parameter is
            omitted).
        acrs:
          type: array
          items:
            type: string
          description: >
            The list of ACR values requested by the device authorization
            request.
        resources:
          type: array
          items:
            type: string
          description: >
            The resources specified by the `resource` request parameters or by
            the `resource` property

            in the request object. If both are given, the values in the request
            object should be

            set. 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.
        expiresAt:
          type: integer
          format: int64
          description: >
            Get the date in milliseconds since the Unix epoch (1970-01-01) at
            which the user code will expire.
        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.
    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.

````