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

{
  "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.

{
    // Response
}
PreviousOAuth 2 Grant FlowsNextAuthorization Flow

Last updated