Device Flow

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.

Authorization Request

First, the client makes a request to the authorization server to request the device code.

POST /device/code HTTP/1.1
Host: authorization-server.com
Content-type: application/x-www-form-urlencoded
 
client_id=a17c21ed&scope=read

Device Code

POST http://app.com/device/code

The client makes a request to the authorization server to request the device code.

Request Body

Name	Type	Description
client_id*	String	the client identifier
scope	String	Define the scopes the application has access to

201: Created The authorization server responds with a JSON payload containing the device code, the code the user will enter, the URL the user should visit, and a polling interval.

{
  "device_code": "e2623df1-8594-47b4-b528-41ed3daecc1a",
  "user_code": "56933A",
  "verification_uri": "http://localhost:4000/activate",
  "verification_full": "http://localhost:4000/activate?audience=Pollich Group&user_code=56933A",
  "audience": "Pollich Group",
  "expires_in": 300,
  "interval": 5
}

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.

Device Activation

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.

Access Token Request

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.

Access Token Request

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.

Request Body

Name	Type	Description
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.

201: Created

{
    // Response
}

400: Bad Request If the client is polling too frequently it will receive an error from the authorisation server

{
  "Status": "bad_request",
  "Link": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/INTERNAL_SERVER_ERROR",
  "Title": "slow_down",
  "Detail": "",
}

400: Bad Request If the user hasn’t yet authorized the client the error will be

{
  "Status": "bad_request",
  "Link": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/INTERNAL_SERVER_ERROR",
  "Title": "authorization_pending, expired_token",
  "Detail": "",
}

401: Unauthorized If the user denies the request, the authorization server will return the access_denied error.

{
  "Status": "unauthorized",
  "Link": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/INTERNAL_SERVER_ERROR",
  "Title": "access_denied",
  "Detail": "",
}

400: Bad Request If the device code has expired, the authorization server will return the expired_token error. The device can immediately make a request for a new device code

{
  "Status": "unauthorized",
  "Link": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/INTERNAL_SERVER_ERROR",
  "Title": "expired_token",
  "Detail": "",
}