Overview

There are several REST API endpoints available to help commission groov EPIC and RIO devices. Some of these endpoints belong to the Authorization service and not groov Manage but will be discussed here because of how they fit in with the rest of the system.

Initial User

On a new device, the first step that should be taken is creating the first system-wide administrator account. This can be done with a POST to the /auth/access/user/commission endpoint. No API key is required when making the first account.

Example data object:

{
  "username": "JoeAdmin",
  "password": "MyPassword"
}

Example cURL command:

curl -k -X POST https://opto-01-02-03/auth/access/user/commission -H "Content-Type: application/json"  -d "{\"username\": \"JoeAdmin\", \"password\": \"MyPassword\"}"

Other Useful Endpoints

The Authorization service has other useful endpoints:

  • /auth/access/user/commission/status
  • /auth/access/user/commission - Submit username + password for the very first user of a new system. Only works when there are no existing admin users.
  • /auth/access/user/commission/form - Submit username + password for the very first user of a new system. Only works when there are no existing admin users.
  • /auth/access/user/login-fetch-api-key - (Added in 4.1 firmware) Authenticate a user and return the user’s API key as plain text. Does not establish a login session.
  • /auth/access/user/login - Submit basic credentials to start a session and gain access to applications on the device.
  • /auth/access/user/logout - Immediately end the current session.

For documentation for the Authorization service’s REST API, please see groov Manage → Info and Help → REST APIs → groov Authentication Service.