---
description: >-
  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.
---

# Device Flow

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

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | String | the client identifier                           |
| scope                                        | String | Define the scopes the application has access to |

{% tabs %}
{% tab title="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." %}
```javascript
{
  "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
}
```
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**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.
{% endhint %}

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.

![](https://994706697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlOWXZIZjvh1Ih2caxSvI%2Fuploads%2FCqkFBR2Xqn5J8Mt2hunR%2FAuthority%20-%20Device%20Activation.png?alt=media\&token=882c9860-9ad7-4e95-a202-66c36fa5924a)

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

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | String | The Device Code grant type value is `urn:ietf:params:oauth:grant-type:device_code`              |
| client\_id<mark style="color:red;">\*</mark>  | String | The client id for which the device code was created                                             |
| code<mark style="color:red;">\*</mark>        | String | The value of `code` should be the `device_code` from the JSON response in the previous request. |

{% tabs %}
{% tab title="201: Created " %}
```javascript
{
    // Response
}
```
{% endtab %}

{% tab title="400: Bad Request If the client is polling too frequently it will receive an error from the authorisation server" %}
```javascript
{
  "Status": "bad_request",
  "Link": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/INTERNAL_SERVER_ERROR",
  "Title": "slow_down",
  "Detail": "",
}
```
{% endtab %}

{% tab title="400: Bad Request If the user hasn’t yet authorized the client the error will be" %}
```javascript
{
  "Status": "bad_request",
  "Link": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/INTERNAL_SERVER_ERROR",
  "Title": "authorization_pending, expired_token",
  "Detail": "",
}
```
{% endtab %}

{% tab title="401: Unauthorized If the user denies the request, the authorization server will return the access_denied error." %}
```javascript
{
  "Status": "unauthorized",
  "Link": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/INTERNAL_SERVER_ERROR",
  "Title": "access_denied",
  "Detail": "",
}
```
{% endtab %}

{% tab title="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" %}
```javascript
{
  "Status": "unauthorized",
  "Link": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/INTERNAL_SERVER_ERROR",
  "Title": "expired_token",
  "Detail": "",
}
```
{% endtab %}
{% endtabs %}
