Device Authorisation Flow

What is Device Authorisation Flow?

With input-constrained devices, rather than authenticate directly, the device asks the user to navigate to a link on their computer or smartphone and authorise the device.

This securely allows the device to obtain credentials for use with the Proximie Platform.

How does it achieve secure Authorization?

The Device Authorisation Flow contains two different paths;

The Device flow path occurs on the device requesting authorisation.

The Browser flow path, wherein a device code is bound to the session in the browser, occurs in parallel to part of the device flow path.

Lets break it down!

The Device Flow

1. To begin the flow the user starts the authentication application on the device.

2. The device app requests authorisation from the Proximie Authorization API using its Client Id

(/oauth/device/code endpoint).

Example request

curl --request POST \
  --url 'https://auth.proximie.net/oauth/device/code' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data scope=SCOPE \
  --data audience=AUDIENCE

3. The Proximie Authorization API responds with the following values

Example response

{
  "device_code": "Ag_EE...ko1p",
  "user_code": "QTZL-MCBW",
  "verification_uri": "https://auth.proximie.net/activate",
  "verification_uri_complete": "https://auth.proximie.net/activate?user_code=QTZL-MCBW",
  "expires_in": 900,
  "interval": 5
}

4. The device app asks the user to activate using their computer or smartphone. The app may accomplish this by:

• asking the user to visit the verification_uri and enter the user_code after displaying these values on-screen

• asking the user to interact with either a QR Code or shortened URL with embedded user code generated from the verification_uri_complete

• directly navigating to the verification page with embedded user code using verification_uri_complete, if running natively on a browser-based device

5. The device app begins polling your Proximie Authorisation API for an Access Token (/oauth/token endpoint) using the time period specified by interval and counting from receipt of the last polling request's response. The device app continues polling until either the user completes the browser flow path or the user code expires.

While you are waiting for the user to activate the device, begin polling the token URL to request an Access Token. Using the extracted polling interval (interval) from the previous step, you will need to POST to the token URL sending along the device_code.

To avoid errors due to network latency, you should start counting each interval after receipt of the last polling request's response.

While you wait for the user to authorize the device, you may receive a few different HTTP 4xx responses. Check the Device Token Errors section for more info on what these are and how to handle them.

Example Token Request

curl --request POST \
  --url 'https://auth.proximie.net/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=urn:ietf:params:oauth:grant-type:device_code \
  --data device_code=YOUR_DEVICE_CODE \
  --data 'client_id=YOUR_CLIENT_ID'

6. Proximie Authorization API waits for the user to complete the Browser Flow

The Browser Flow

1. The user visits the verification_uri on their computer, enters the user_code and confirms that the device that is being activated is displaying the user_code. If the user visits the verification_uri_complete by any other mechanism (such as by scanning a QR code), only the device confirmation will be needed.

2. Proximie redirects the user to the login and consents prompt if needed.

3. The user authenticates and may be presented with a consent page asking to authorise the device app and assign an organisation and nickname.

4. Your device app is authorised to access the API.

The Device Flow (Post Authorisation)

7. When the user completes the browser flow path, Proximie Authorization API responds with an Access Token and a Refresh Token. The device app should now forget its device_code because it will expire.

Example Token response

{
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "token_type":"Bearer",
  "expires_in":86400
}

8. Your device app can use the Access Token to subscribe to the device control API and other Proximie APIs.

9. API Responses successfully

Full overview of the flow from start to finish.

Device Token Errors

Authorization pending

You will see this error while waiting for the user to take action. Continue polling using the suggested interval retrieved in the previous step of this document.

{
  "error": "authorization_pending",
  "error_description": "..."
}

Slow down

You are polling too fast. Slow down and use the suggested interval retrieved in the previous step of this tutorial. To avoid receiving this error due to network latency, you should start counting each interval after receipt of the last polling request's response.

{
  "error": "slow_down",
  "error_description": "..."
}

Expired token

The user has not authorized the device quickly enough, so the device_code has expired. Your application should notify the user that the flow has expired and prompt them to reinitiate the flow.

❗️

The expired_token error will be returned exactly once; after that, the dreaded invalid_grant will be returned. Your device must stop polling.

{ 
  "error": "expired_token",
  "error_description": "..."
}

Access denied

Finally, if access is denied, you will receive:

{
  "error": "access_denied",
  "error_description": "..."
}