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

Parameter

Description

Format

name

The role name. For example, the plugin name.
Mandatory.

String

description

The role description.
Optional

String

permissionIds

An 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

Parameter

Description

Format

permissionIds

An 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'

Parameter

Description

Format

active

Is the service user active or not.
Set to true.
Optional.

Boolean

roleId

The role ID obtained in step 1.
Mandatory

String

type

The type of service user.
Use "INTERNAL_SERVICE".
Mandatory

String

ownerOrganizationId

The owner organization.
Use "00000000-0000-0000-0000-000000000000"
Mandatory.

String

name

The name of the service user.
You may use the plugin name.
Optional.

String

accessTokenExpirationInMinutes

The 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.


Did this page help you?