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.
...
| 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. |
...
| Code Block |
|---|
POST https://testing.booxmedia.xyz/api/auth/v1/device
client_id={CLIENT_ID} |
...
The server will respond with a JSON document with a few pieces of information.
| Code Block |
|---|
{ "device_code": "NGU4QWFiNjQ5YmQwNG3YTdmZMEyNzQ3YzQ1YSA", "verification_uri": "https://example.com/device", "user_code": "BDSD-HQMK", "expires_in": 1800, "interval": 5 } |
...
Here’s what the properties in the response mean:
device_code- This is a long string that the device will use to eventually exchange for an access token.verification_uri- This is the URL the user needs to enter into their phone to start logging in.user_code- This is the text the user will enter at the URL above.expires_in- The number of seconds that this set of values is valid. After this amount of time, thedevice_codeanduser_codewill expire and the device will have to start over.interval- The number of seconds the device should wait between polling to see if the user has finished logging in.
Now the device needs to display the URL and User Code to the user somehow. 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 |
|---|
POST https://authorization-server.com/token
grant_type=urn:ietf:params:oauth:grant-type:device_code
&client_id=CLIENT_ID
&device_code=NGU4QWFiNjQ5YmQwNG3YTdmZMEyNzQ3YzQ1YSA |
...
While the user is busy logging in on their phone, the token endpoint will return the error message below:
| Code Block |
|---|
{ |
...
"errors": [
{
"id": "6de7da3e-8877-4f2b-a670-16e18e5d79a0",
"status": "202",
"code": "0",
"title": "Authentication Pending",
"detail": " - User is not yet authenticated, try again."
}
]
} |
The authorization_pending error means the user isn’t finished logging in, but the code hasn’t yet expired either. The device should try this again after the specified number of seconds. Meanwhile the user will be logging in, choosing a YouTube account, and approving the request.
...