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

ParameterDescriptionFormat
nameThe role name. For example, the plugin name.
Mandatory.
String
descriptionThe role description.
Optional
String
permissionIdsAn array of permission IDs that this role will hold.
Optional.
String Array

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

ParameterDescriptionFormat
permissionIdsAn array of permission IDs that this role will hold.
Mandatory.
String Array

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'

ParameterDescriptionFormat
activeIs the service user active or not.
Set to true.
Optional.
Boolean
roleIdThe role ID obtained in step 1.
Mandatory
String
typeThe type of service user.
Use "INTERNAL_SERVICE".
Mandatory
String
ownerOrganizationIdThe owner organization.
Use "00000000-0000-0000-0000-000000000000"
Mandatory.
String
nameThe name of the service user.
You may use the plugin name.
Optional.
String
accessTokenExpirationInMinutesThe token expiration time in minutes.
Optional.
Integer

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.