# Device Code Flow

Device code flow allows users to sign in to input-constrained devices such as a smart TV,
IoT device, or a printer. To enable this flow, the device has the user visit a webpage in
a browser on another device to sign in. Once the user signs in, the device is able to get
access tokens and refresh tokens as needed.

The response supplies an `expires_in` and an `interval` for how often
and how long you should poll for the token. A `device_code` for authenticating
when polling the token. And a `verification_uri` and a
`verification_uri_complete` for returning to user who must authorize the request.

## Device authorization request

Requesting tokens with device code flow is done by sending a request to the `POST /connect/deviceauthorization` endpoint.
The request body requires `client_id`, and `scope`.

### POST /connect/deviceauthorization


```HTTP Request
POST https://id.aritma.io/{tenant}/connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

  scope=SCOPE&
  client_id=YOUR_CLIENT_ID&
  client_secret=YOUR_CLIENT_SECRET
```


```HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json
{
  "device_code": "F3E37A471A...74B033B4C7",
    "user_code": "12345678",
    "verification_uri": "https://id.aritma.io/{tenant}/device",
    "verification_uri_complete": "https://id.aritma.io/{tenant}/device?userCode=12345678",
    "expires_in": 300,
    "interval": 5
}
```

| Parameter | Description |
|  --- | --- |
| `scope` (required) | The scopes which you want to request authorization for. These must be separated by a space. You can request any of the standard OpenID Connect (OIDC) scopes about users, such as profile and email, or any scopes supported by the target API (for example, banking.ais.read). Include offline_access to get a Refresh Token. |
| `client_id` (required) | Your application's Client ID. |
| `client_secret` (optional) | Your application's Client Secret, if needed. |


## Poll token

Once you have received your `device_code` it's time to poll until you recieve an usable access token, or the request expires.
This is done using the `/connect/token` endpoint. In short you send a token request with
`urn:ietf:params:oauth:grant-type:device_code` together with the supplied `device_code` and your `client_id`.

### POST /connect/token


```HTTP
POST https://id.aritma.io/{tenant}/connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

  grant_type=urn:ietf:params:oauth:grant-type:device_code&
  client_id=YOUR_CLIENT_ID&
  device_code=DEVICE_CODE
```


```HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"eyJz93a...k4laUWw",
  "id_token":"eyJ0XAi...4faeEoQ",
  "token_type":"Bearer",
  "scope":"openid",
  "expires_in":3600
}
```


```HTTP Response
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error":"authorization_pending",
}
```

| Parameter | Description |
|  --- | --- |
| `grant_type` (required) | Denotes the flow you are using. For Device Code use `urn:ietf:params:oauth:grant-type:device_code` |
| `client_id` (required) | Your application's Client ID. |
| `device_code` (required) | The Authorization request id received from the initial `POST /connect/deviceauthorization` call. |


| Error | Description |
|  --- | --- |
| `authorization_pending` | The authorization request is still pending. (keep polling) |
| `slow_down` | A variant of `authorization_pending`, the authorization request is still pending, but the interval MUST be increased by atleast 5 seconds. |
| `expired_token` | The `auth_req_id` has expired, the client must create a new authorization request. |
| `access_denied` | The user denied the authorization request. |