Introduction
...
| 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. |
...
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 browser to start logging in.user_code- This is the code the user will enter at the URL above, it will be of 8 characters, upper case A-Z and numeric.expires_in- The number of seconds that this set of values is valid. After this amount of time, thedevice_codeanduser_codewill expire and the process will have to start over.interval- The number of seconds the device should wait between polling to see if the user has finished authentication.
Now the device needs to display the URL and User Code to the user.
| Info |
|---|
UI Client is free to add spaces or dashes to the user code (ex. ABCD-1234) in order to make it easier to read and enter into the secondary device, as long as all such characters are stripped from the input when they send it back to uswhile requesting for the verification. |
Verification:
User logs in with regular authentication mechanism to the service from mobile phone/browser, then enters the verification_uri provided by the device endpoint, a POST request is made to /api/auth/v1/device/verify endpoint to verify the user. See: User Authentication#/Device%20Authorization/verifyUserCode
...
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\”}” |
...