Creating a Service User for Your Plugin

When writing your plugin, service users can be used to communicate securely with the BioT platform.
Service users are not regular users and have a unique access key ID and secret key that allows them to log in to BioT before each API call session that they want to perform.

📘

Note

The following steps involve making manual API calls. We recommend using a GUI tool to help with the process such as the free Postman tool. For a quick tutorial of how to use it, see Getting Started.

To create a service user, follow these steps:

1. Create a role
2. Add permissions to the role
3. Create a service user with the role (from step 1)

Create a Role

A role holds several permissions

To create a Role, make a REST call to:
POST https://your-biot-domain.com/ums/v2/admin/roles

The response will hold the role ID created in BioT. Save this ID as you will need to use it in the next steps.

For example:

{
   "name":"string",
   "description":"string",
   "id":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "type":"INTERNAL",
   "permissions":[
      {
         "id":"string"
      }
   ],
   "creationTime":"2022-07-18T14:17:07.451Z",
   "lastModifiedTime":"2022-07-18T14:17:07.451Z"
}

Add Permissions to the Role

In most cases, you will be able to skip this step.

Most of the REST APIs in BioT are not protected by permissions and are instead protected by BioT's attribute based access control system that will allow or deny access to a specific API.
To determine if an API needs a specific permission, search for it in the API reference.
If an API requires a permission, you will see a specific indication for it, like in this API.

Permissions can be added during the role creation stage or with this API call:
POST https://your-biot-domain.com/ums/v2/admin/roles/{id}/permissions/associate

Create a Service User with the Role (from step 1)

Finally, create the service user with this API call:
POST '<https://your-biot-domain.com/ums/v2/services>'

The response will hold the new service user credentials.
For example:

{
   "active":true,
   "roleId":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "type":"EXTERNAL_SERVICE",
   "ownerOrganizationId":"00000000-0000-0000-0000-000000000000",
   "name":"string",
   "accessTokenExpirationInMinutes":0,
   "id":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "secretKeyData":{
      "id":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "creationTime":"2022-07-18T14:41:17.152Z",
      "secretKey":"string"
   }
}

📘

Note

The ID and secret key parameters are used as the login credentials for the plugin and must be kept secret.

Set the ID and secret key in the environment variables of the plugin.
For more information, see Sample Plugin Code.

Specifying an Organization

By default, a service user does not belong to an organization. This means that some API calls requiring organizational affiliation will fail. To specify an organization, add the following header to the API call:
"Tenant-Id": "Organization-Id"