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. An device_code for authenticating when polling the token. And a device_code, 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

RequestResponse

Copy

Copied

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

Copy

Copied

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

RequestResponseResponse

Copy

Copied

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

Copy

Copied

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
}

Copy

Copied

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.