Sign in
Device Flow

Process Device Verification Request

The API returns information associated with a user code.

Description

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.

post/api/{serviceId}/device/verification

Path parameters

serviceIdstring required

A service ID.

Request body

userCodestring required

A user code.

Response

Device verification completed successfully

resultCodestring

The code which represents the result of the API call.

resultMessagestring

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

action'INTERNAL_SERVER_ERROR' | 'NOT_EXIST' | 'EXPIRED' | 'VALID'

The next action that the authorization server implementation should take.

clientIdinteger

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

clientIdAliasstring

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

clientIdAliasUsedboolean

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.

clientNamestring

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

claimNamesstring[]

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

acrsstring[]

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

resourcesstring[]

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.

expiresAtinteger

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

gmAction'CREATE' | 'QUERY' | 'REPLACE' | 'REVOKE' | 'MERGE'

The grant management action of the device authorization request.

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

grantIdstring

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.

grantSubjectstring

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.

clientEntityIdstring

The entity ID of the client.

clientEntityIdUsedboolean

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

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

metadataDocumentUsedboolean

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.

Changes