--- title: "Complete Device Authorization" method: POST path: "/api/{serviceId}/device/complete" tags: ["Device Flow"] --- # Complete Device Authorization `POST /api/{serviceId}/device/complete` 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. ### Description 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. ## Path parameters - `serviceId` string, required ## Request body - DeviceCompleteRequest - `userCode` string, required — A user code. - `result` 'TRANSACTION_FAILED' | 'ACCESS_DENIED' | 'AUTHORIZED', required — The result of the end-user authentication and authorization. One of the following. Details are described in the description. - `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 — 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` Property[] — The extra properties associated with the access token. - `key` string — The key part. - `value` string — The value part. - `hidden` boolean — 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. - `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 — 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 — 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. | 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. ## Response `200` - DeviceCompleteResponse - `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` 'SERVER_ERROR' | 'USER_CODE_NOT_EXIST' | 'USER_CODE_EXPIRED' | 'INVALID_REQUEST' | 'SUCCESS' — The next action that the authorization server implementation should take. ## Other responses - `400` - `401` - `403` - `500` --- [API](https://skmtc.dev/authlete/apis/authlete-api.md) · [All operations](https://skmtc.dev/authlete/apis/authlete-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/authlete/authlete-api/revisions/8a534bc68775/schema)