# The Device Flow
Device Flow
There are situations in which devices or on-premise software need to connect to cloud resources. Such devices might not have a browser and thus cannot support the usual OAuth redirect flow. In these cases you can use the device authorisation flow to obtain connectivity.
The device flow is split into two parallel streams: the device itself will request access from the Zaikio Hub and then display a URL or QR code for user confirmation. The user uses a second device, such as a mobile phone or a PC with a browser, to open the aforementioned URL (or scan a QR code) and confirm the authorisation request.
While the user is doing this, the device will periodically query the authentication server to figure out if the authorisation was already granted by the user. If so, the device will be issued an access token and the process concludes.
# Device authentication flow
The Zaikio Hub supports the device authentication flow based on the standard device authorization grant type (RFC 8628) (opens new window). In order to use this flow you need to create an App (which can be either public or private) in the Zaikio Hub.
In order to connect, the following steps are necessary:
- Your device requests a device authorisation grant
- Your device instructs the user to go to a URL or scan a QR code for confirmation
- Your device starts polling the Zaikio Hub for an access token, and receives it once the user confirmed access
- Your device starts making API calls, such as querying the Zaikio Hub API for user information
# Your device requests a device authorisation grant
To start the device authorisation OAuth flow, you need to send a POST request to https://hub.zaikio.com/oauth/device_authorizations/authorize.
The following parameters are supported for this request:
| Name | Required | Description |
|---|---|---|
| client_id | Required | The client ID for your App as generated by the Zaikio Hub. |
| scope | A comma-seperated list of the scopes you want authorisation for. Please read the scope guides. |
# Your device instructs the user to go to a URL or scan a QR code for confirmation
The Zaikio Hub returns a device code, a user code and a verification URL after step 1 is completed. You must present the verification URL to the user, so she can use a browser to get to that URL. You can also present a QR code which contains the URL for scanning with a mobile phone. You must also display the user code on your device and instruct the user to enter this 8 digit code in the mask that appears in the browser after going to the confirmation URL.
The response also contains the verification_url_complete. This URL already contains the confirmation code. It is recommended to use this URL as the basis for the QR code. After scanning, the user will be presented with the same mask as before, but the code will be pre-filled. Thus the user just needs to confirm that the code displayed by your device is the same that is shown in the Zaikio Hub.
# Your device starts polling the Zaikio Hub for an access token, and receives it once the user confirmed access
As soon as you receive the authorisation information from step 1 and display confirmation information as described in step 2 your device must start querying the Zaikio Hub if the authorisation has already been granted. The interval that needs to pass between two polling attempts is specified in the interval parameter which is returned in the response for step 1.
To start polling you need to send a POST request to https://hub.zaikio.com/oauth/access_token.
The following parameters must accompany the polling request:
| Name | Required | Description |
|---|---|---|
| client_id | Required | The client ID for your App as generated by the Zaikio Hub. |
| grant_type | Required | The value must be set to urn:ietf:params:oauth:grant-type:device_code. |
| device_code | Required | The device_code parameter as received in step 1. |
According to the state of the authorisation process in the Zaikio Hub you will receive one of the following responses. Depending on the HTTP Accept header send with your request, the response will either be plain text, JSON or XML. Described below are examples of the JSON responses, the others contain the same information.
# access_denied response
The authorisation request was denied and you must abort the process.
# expired_token response
The device authorisation grant has expired, because the user took too long to authorise it. You must restart the process, starting from step 1.
# authorization_pending response
The authorisation was not yet given by the user in the Zaikio Hub, you should keep polling using the given interval.
# slow_down response
A variant of "authorization_pending", the authorization request is still pending and polling should continue, but the interval must be increased by 5 seconds for this and all subsequent requests.
The authorization_pending and slow_down error codes define particularly unique behaviour, as they indicate that the OAuth client should continue to poll the token endpoint by repeating the token request (implementing the precise behavior defined above). If the client receives an error response with any other error code, it must stop polling and should react accordingly, for example, by displaying an error to the user.
# Access granted response
{
"access_token": "749ceefd1f7909a1773501e0bc57d5b2",
"refresh_token": "be4ae927cf49466293049c993ad911b2",
"token_type": "bearer",
"scope": "zaikio.person.read",
"audiences": ["directory"],
"expires_in": "2019-12-03T08:57:35.958Z",
"bearer": {
"id": "29b276b7-c0fa-4514-a5b1-c0fb4ee40fa7",
"type": "Person"
}
}
# Your device starts making API calls, such as querying the Zaikio Hub API for user information
In order to retrieve information about the current user (like email address, name and organisation memberships) you need to query the Zaikio Hub V1 REST API at GET https://hub.zaikio.com/api/v1/person. Please note that contrary to the token exchange response, the API only responds with JSON. In order to gain access to the following information, you must have asked for authorisation for the zaikio.person.read scope.
To authenticate against the API the Authorization header must be set to
Bearer <your API token>
where <your API token> must be replaced with the token you obtained in step 3.
An example call to this endpoint might look like this:
curl --request GET \
--url https://hub.zaikio.com/api/v1/person \
--header 'Authorization: Bearer 749ceefd1f7909a1773501e0bc57d5b2'