Skip to main content
POST
/
api
/
{serviceId}
/
device
/
complete
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.complete({
    serviceId: "<id>",
    deviceCompleteRequest: {
      userCode: "XWWKPBWVXQ",
      result: "AUTHORIZED",
      subject: "john",
    },
  });

  console.log(result);
}

run();
{
  "resultCode": "A241001",
  "resultMessage": "[A241001] The API call was processed successfully.",
  "action": "SUCCESS"
}
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.

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.

​
result
enum<string>
required

The result of the end-user authentication and authorization. One of the following. Details are described in the description.

Available options:
TRANSACTION_FAILED,
ACCESS_DENIED,
AUTHORIZED
​
subject
string
required

The subject (= unique identifier) of the end-user.

​
sub
string

The value of the sub claim that should be used in the ID token.

​
authTime
integer<int64>

The time at which the end-user was authenticated. Its value is the number of seconds from 1970-01-01.

​
acr
string

The reference of the authentication context class which the end-user authentication satisfied.

​
claims
string

Additional claims which will be embedded in the ID token.

​
properties
object[]

The extra properties associated with the access token.

​
scopes
string[]

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
string

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
string

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
string

JSON that represents additional JWS header parameters for ID tokens.

​
consentedClaims
string[]

the claims that the user has consented for the client application to know.

​
jwtAtClaims
string

Additional claims that are added to the payload part of the JWT access token.

​
accessTokenDuration
integer<int64>

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

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
string

The type of the aud claim of the ID token being issued. Valid values are as follows.

ValueDescription
"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.
nullThe type of the aud claim remains the same as before.

This request parameter takes precedence over the idTokenAudType property of the service.

Response

​
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:
SERVER_ERROR,
USER_CODE_NOT_EXIST,
USER_CODE_EXPIRED,
INVALID_REQUEST,
SUCCESS