Overview
This document describes general device behavior in PrintOS. The document covers the following topics:
- Provisioning: The initial provisioning of the device to PrintOS cloud services under the proper organization
- Credentials: The device receiving its own set of credentials
- Login: The device storing the credentials and logging in
- Session ID: The device using the session ID returned upon login to make other REST calls
The document also describes the following situations:
- Device re-login after expiration of the session ID
- Sending real-time status data
Device Provisioning
Before a device can interact with PrintOS, it needs to be provisioned. Provisioning is the process of getting the device established as an entity in the system, within the correct organization, and getting the device a set of credentials. Here are the detailed steps:
- Administrator Login - The device is expected to have a "cloud activation" UI screen to allow a PSP administrator to "Activate" the device for cloud access. At this screen the PSP administrator will enter their username and password. The device will login as the administrator and save the user session ID token that is returned.
- Device Creation - The device will create a device call using the Administrator user’s session ID. A login and password for the new device will be included in the response. The device must encrypt and store these credentials for later use.
- Administrator Logout - The device will logout the Administrator user.
- Device Login - The device will login with the newly generated device credentials. The device credentials must be used by the device. This allows the device to continue to work even if the administrator who provisioned the device leaves the company.
- Device Status - The device can provide status updates as long as the session ID is valid. See Device Status section for additional details on providing status.
Administrator Login
The first step in the provisioning process requires a PSP administrator to provide their credential so that they can be logged into PrintOS. Using the administrator’s credentials the device will login using the /api/aaa/v3/users/login endpoint. A successful call will return a 200 – OK status and will set the Indigo-Sms-Auth-Token to the user’s session ID.
|
Endpoint |
HTTP Method |
|---|---|
| POST | /api/aaa/v3/users/login |
NOTE: Before logging on as an administrator over the API, the PSP account administrator must first login to the user interface and accept the End-User License Agreement (EULA) that appears during the first login.
Example Request Body
{
"login":"username",
"password":"password"
}
Example Response
{
"user": {
"locked": false,
"userId": "38af8e01-1057-4a38-bf1a-ea28b3c441a9",
"firstName": "John",
"lastName": "Smith",
"displayName": "John Smith",
"primaryAddress": {},
"createdTime": 1453881539000,
"invalidAttempts": 0,
"expireTime": "2019-06-12 21:42:06.0"
},
"type": "User",
"context": {
"id": "b7f516cd-49d4-4a12-9d53-a5c146c846c6",
"name": "ABC PSP",
"type": "PSP"
}
}
Device Creation
The second step in the provisioning process is to create the PrintOS representation of the device. Using the session ID (context.id) from step one and additional information, the device will call the create device API. This call will return a login and password for the newly created device. The login and password must be stored as encrypted data (AES, Blowfish…).
|
Endpoint |
HTTP Method |
HTTP Header |
|---|---|---|
| POST | /api/aaa/v3/organizations/devices | Indigo-SmS-Auth-Token |
- An HTTP header named Indigo-Sms-Auth-Token should be set to the value of the session ID (context.id) from step one.
Example Request Body
{
"name": "MBO M60",
"serialNumber": "22001148",
"type": "FinishingDevice",
"model": "MBO_M60",
"securityPassword”: "password"
}
The type and model fields must match the information provided to HP for this device or the device creation call will fail.
Example Response
{
"device": {
"active": true,
"locked": false,
"deviceId": "139a941a-03be-4a87-8dae-8d8a4125e66e",
"name": "MBO M60,
"serialNumber": "22001148",
"model": "MBO_M60",
"type": "FinishingDevice",
"organizationId": "b7f516cd-49d4-4a12-9d53-a5c146c846c6",
"anonymous": false,
"createdTime": 1461873751000
},
"credentials": {
"login": "2of9q0tmbqet8ol23kmoduedik",
"password": "6310lqgmmd4js733op6tst3nb2"
}
}
Administrator Logout
Once the device has been created and a login and password have been received, the PSP administrator will be logged out by the device calling the following API.
|
Endpoint |
HTTP Method |
HTTP Header |
|---|---|---|
| POST | /api/aaa/v3/users/logout | Indigo-SmS-Auth-Token |
-
An HTTP header named Indigo-Sms-Auth-Token should be set to the value of the session ID (context.id) from step one.
Device Login
At this point the device is provisioned, has a set of credentials and can log into PrintOS by calling the login device API. A successful call will return a 200 – OK status and will set the Indigo-Sms-Auth-Token to the device’s session id.
|
Endpoint |
HTTP Method |
|---|---|
| POST | /api/aaa/v3/devices/login |
Example Request Body
{
"login": "2of9q0tmbqet8ol23kmoduedik",
"password": "6310lqgmmd4js733op6tst3nb2"
}
Example Response
{
"device": {
"active": true,
"locked": false,
"deviceId": "139a941a-03be-4a87-8dae-8d8a4125e66e",
"name": "MBO M60,
"serialNumber": "22001148",
"model": "MBO_M60",
"type": "FinishingDevice",
"organizationId": "b7f516cd-49d4-4a12-9d53-a5c146c846c6",
"anonymous": false,
"createdTime": 1461873751000
},
"type": "Device",
"context": {},
"authToken": "a6f04k3tlus1vf8cl10c0rf426",
"expire": "Fri Apr 29 02:20:48 UTC 2016"
}
- The authToken returned in the response should be included as the Indigo-SmS-Auth-Token HTTP header in subsequent calls to PrintOS.
The “expire” field in the response is the expiration time of the device's session ID. If a call is made to PrintOS with an expired device session ID the call will return a 401 – Unauthorized which means the device needs to login again to receive a new device session ID.