The OAuth 2.0 “Device Flow” extension enables OAuth on devices that have an Internet connection but don’t have a browser or an easy way to enter text.
This flow is seen on devices such as smart TVs, media consoles, picture frames, printers, or hardware video encoders. In this flow, the device instructs the user to open a URL on a secondary device such as a smartphone or computer in order to complete the authorization. There is no communication channel required between the user’s two devices.
First, the client makes a request to the authorization server to request the device code.
POST http://app.com/device/code
The client makes a request to the authorization server to request the device code.
| Name | Type | Description |
|---|---|---|
Note that some authorization servers will allow the device to specify a scope in this request, which will be shown to the user later on the authorization interface.
After validating the client ID and scopes, the authorization server returns the response with the verification URL, device code, and user code. There are a few optional parameters that the authorization server can return in addition to the example given above.
device_code – Required, the verification code generated by the authorization server.
user_code – Required, the code the user will enter on the device screen should be relatively short. Typically 6-8 numbers and letters are used.
verification_uri – Required, the URL on the authorization server that the user should visit to begin authorization. The user is expected to hand-enter this URL on their computer or mobile phone.
expires_in – Optional, the lifetime in seconds of the device code and user code.
interval – Optional, the minimum amount of time in seconds that the client should wait between polling requests to the token endpoint.
The device shows the verification_uri and user_code to the user on its display, directing the user to enter the code at that URL.
Visiting that URL after you’ve signed in to your account shows an interface that prompts you to enter the code that’s displayed on the device.
Meanwhile, the client should attempt to acquire an access token every few seconds (at a rate specified by interval) by POSTing to the access token endpoint on the authorization server.
While the device is waiting for the user to complete the authorization flow on their own computer or phone, the device meanwhile begins polling the token endpoint to request an access token.
POST https://app.com/device/token
The device makes a POST request with the device_code at the rate specified by interval. The device should continue requesting an access token until a response other than authorization_pending is returned, either the user grants or denies the request or the device code expires.
| Name | Type | Description |
|---|---|---|
client_id*
String
the client identifier
scope
String
Define the scopes the application has access to
grant_type*
String
The Device Code grant type value is urn:ietf:params:oauth:grant-type:device_code
client_id*
String
The client id for which the device code was created
code*
String
The value of code should be the device_code from the JSON response in the previous request.