...
...
...
...
Introduction
The device authorisation grant is designed for Internet connected devices that either lack a browser to perform a user-agent based authorisation or are input constrained to the extent that requiring the user to input text in order to authenticate during the authorisation flow is impractical. It enables clients on such devices (like smart TVs, media consoles, digital picture frames, and printers) to obtain user authorisation to access protected resources by using a user agent on a separate device.
Device-Auth User flow
This section describes how device authorisation flow can be achieved from a device.
API Spec: User Authentication#/Device%20Authorization
Endpoint specifications:
| Endpoint | HTTP Method | Purpose |
|---|---|---|
| /api/auth/v1/device | POST | Creates unique user code and a verification URI to present it on a external browser to verify the user. |
| /api/auth/v1/device/verify | POST | Verifies the user code with the authenticated user. |
| /api/auth/v1/access_token grant_type="urn:ietf:params:oauth:grant-type:device_code" | POST | Provides access_token to the device once the user is verified externally. |
Use Case:
1. User Turn on device (e.g: STB) first time
2. User is prompted with a random 8 characters code (aka user_code)
3. User is prompted to go to a website to login (authenticate)
4. Once successfully authenticated, user will be asked to enter the user_code from step 2
5. User enter user_code and submit it
6a. If user_code is valid => the device (in #1) will be successfully login => user can start streaming services entitled to his/her account.
6b. If user_code is invalid => the device (in #1) will prompt user that login was failed => user won't be able to use any services.
...
While the device waits for the user to enter the code and log in, it will make a POST request every 5 seconds as specified by the interval returned. This POST request will be made to the /api/auth/v1/access_tokenendpoint, using a grant type of urn:ietf:params:oauth:grant-type:device_code
| Code Block |
|---|
curl -X POST "https://testing.booxmedia.xyz/api/auth/v1/access_tokens" -H "accept: application/vnd.api+json" -H "Content-Type: application/json" -d "{\"grant_type\":\"urn:ietf:params:oauth:grant-type:device_code
\",\"credentials\”:{\”client_id\”:\”1234xyz”, \”device_code\”:\”NGU4QWFiNjQ5YmQwNG3YTdmZMEyNzQ3YzQ1YSA
”},\”login_user_profile\":\"84eb61a9-75d4-42c7-8c15-84c3d7776227\”}” |
...