Skip to main content
POST
/
api
/
{serviceId}
/
device
/
verification
Typescript (SDK)
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();
{
  "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"
    }
  ]
}
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.

Authorizations

​
Authorization
string
header
required

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.

Path Parameters

​
serviceId
string
required

A service ID.

Body

​
userCode
string
required

A user code.

Response

Device verification completed successfully

​
resultCode
string

The code which represents the result of the API call.

​
resultMessage
string

A short message which explains the result of the API call.

​
action
enum<string>

The next action that the authorization server implementation should take.

Available options:
INTERNAL_SERVER_ERROR,
NOT_EXIST,
EXPIRED,
VALID
​
clientId
integer<int64>

The client ID of the client application to which the user code has been issued.

​
clientIdAlias
string

The client ID alias of the client application to which the user code has been issued.

​
clientIdAliasUsed
boolean

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
string

The name of the client application to which the user code has been issued.

​
scopes
object[]

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
string[]

The names of the claims which were requested indirectly via some special scopes. See 5.4. Requesting Claims using Scope Values 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
string[]

The list of ACR values requested by the device authorization request.

​
resources
string[]

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
object

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

​
serviceAttributes
object[]

The attributes of this service that the client application belongs to.

​
clientAttributes
object[]

The attributes of the client.

​
dynamicScopes
object[]

The dynamic scopes which the client application requested by the scope request parameter.

​
expiresAt
integer<int64>

Get the date in milliseconds since the Unix epoch (1970-01-01) at which the user code will expire.

​
gmAction
enum<string>

The grant management action of the device authorization request.

The grant_management_action request parameter is defined in Grant Management for OAuth 2.0.

Available options:
CREATE,
QUERY,
REPLACE,
REVOKE,
MERGE
​
grantId
string

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 , which is supported by Authlete 2.3 and newer versions.

​
grant
object
​
grantSubject
string

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. 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, {@link #getGrantSubject()} 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 {@link #getGrantSubject()} 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
string

The entity ID of the client.

​
clientEntityIdUsed
boolean

Flag which indicates whether the entity ID of the client was used when the request for the access token was made.

​
metadataDocumentLocation
string<uri>

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 (CIMD) mechanism.

​
metadataDocumentUsed
boolean

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.