Skip to content

User Management and Access Control

In the IDV Platform, Users work with different levels of access.

Access is managed via Roles and Permissions:

  • Role is a collection of Permissions grouped together. Assigning a Role gives a user all the Permissions inside it.
  • Permission defines what action can be done and where. For example, the session:read permission lets a user view their Sessions. Permission consists of a pair: Scope + Operation.
  • Scope defines where the Permission applies. For example, session gives access to only the user’s own sessions, while session_all gives access to everyone’s sessions.
  • Operation defines what action can be done.

Scopes

Scope Description
session_all Access to all Sessions.
session Access to User’s own Sessions.
session_all_patch Ability to change state of all Sessions.
session_patch Ability to change state of own Sessions.
session_analytics Access to Session Analytics.
registry Access to Registry.
secret Access to Secrets.
view Access to all Views everywhere except POST /namespaces/{namespace}/key/{key}, where it grants access only to user’s own views.
view_all Access to all Views, but only in POST /namespaces/{namespace}/key/{key}.
workflow Access to User’s own Workflows.
workflow_all Access to all Workflows.
workflow_reload Ability to reload Workflows from storage.
user Access to Users.
audit Access to Audit.
monitoring Access to Monitoring.
device Access to User’s own Devices.
device_all Access to all Devices.
device_log Access to Device logs.
group Access to User Groups.
docreader Access to DocReader service.
faceapi Access to FaceAPI service.
person Access to Persons.
pool Access to User’s own Profile Groups.
pool_all Access to all Profile Groups.
pool_access Access to Profile Groups Permissions.
translations Access to Workflow Translations.
assets Access to Workflows Assets.
apikey Access to User’s own API keys.
apikey_all Access to all API keys.
ephemeral_device Access to Ephemeral Devices.
roles Access to all Roles (custom and default).

Operations

Operation Description
read Allows to get a single entity, or a set of entities.
write Allows to modify an entity or a set of entities. For example, replace entire entity or partially update it.
delete Allows to delete an entity or a set of entities.
subscribe Allows to receive real-time changes of an entity. For example, session:subscribe shows updates in the UI as soon as a session’s state changes.

User Roles

You can use out-of-the-box Roles or create your custom ones.

Default

The following default Roles are available in the Platform:

Role Description Permissions
Admin Full access to all data and settings. Can manage Users, Profiles, Workflows. all the available permissions
Verifier Can view and verify data but does not have administrative rights. session_all_patch:write, session_all:read, session_all:write, session_all:delete, session_all:subscribe, session:read, session:write, session:subscribe, session_patch:write, registry:read, registry:write, registry:delete, workflow:read, workflow_all:read, view:read, view:write, view:delete, group:read, secret:read, secret:write, secret:delete, pool:read, person:read, person:write, person:delete
Device A technical role used to register and connect devices to the Platform. session:read, session:write, session:subscribe, registry:read, registry:write, registry:delete, workflow:read, group:read, docreader:write, faceapi:write, secret:read, secret:write, secret:delete, device_log:write
Demo A special role used for demo scenarios (typically required only once for demonstration purposes). session:read, session:write, session:subscribe, session_patch:write, registry:read, registry:write, registry:delete, view:read, view:write, view:delete, workflow:read, docreader:write, faceapi:write, secret:read, roles:read

Custom

In addition to built-in Roles, you can create Custom Roles. Custom Roles are assembled from available Permissions, enabling flexible configuration of access rights.

You can create Custom Roles via the API. The following request will create a Session Observer Custom Role with the session:read and session:subscribe permissions:

curl -X 'POST' \
  'https://nightly-idv.regula.app/api/security/roles' \
  -H 'accept: application/json' \
  -H 'Authorization: Token <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Session Observer",
  "permissions": [
    "session:read", "session:subscribe"
  ]
}'

Response example:

{
  "name": "Session Observer",
  "isSystem": false,
  "permissions": {
    "session": [
      "read",
      "subscribe"
    ]
  }
}

isSystem: false means that this is a Custom Role.

User Creation

You can create Users in several ways:

  • SSO / Identity Provider (IdP) – integration with corporate IdPs (for example, Google, Azure AD, Okta).

  • Platform Portal (UI) – manual creation and management of Users via the built-in admin interface.

To create a new User, navigate to the Settings tab, expand the Team group, and select Users. In the upper right corner, click on the + Add new user button.

Adding a user

  • API – programmatic creation and management of Users through the Platform API.

A new user can be created via the API by sending a POST request to the /api/security/users endpoint. This endpoint accepts the following fields in the request body:

Field Description
name Username, must be unique across all the users.
email User's email.
password User's password.
active If false, the User will not be able to do anything, even log in to the Platform.
firstName User's first name.
lastName User's last name.
roles A list of Role names associated with a User.
attributes Arbitrary data associated with a User. 
curl -X 'POST' \
  'https://nightly-idv.regula.app/api/security/users' \
  -H 'Authorization: Token <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "John Doe",
  "email": "johndoe@example.com",
  "password": "39a8d61eba05",
  "active": true,
  "firstName": "John",
  "lastName": "Doe",
  "roles": [
    "demo"
  ],
  "attributes": {
    "department": "sales"
  }
}'

Response example:

{
  "id": "68cd5a091541616e810b1c0e",
  "name": "John Doe",
  "email": "johndoe@example.com",
  "active": true,
  "firstName": "John",
  "lastName": "Doe",
  "roles": [
    "demo"
  ],
  "attributes": {
    "department": "sales"
  },
  "external": {},
  "type": "internal"
}

Access Restrictions

Access to Views, Sessions, and Workflows

Access can be restricted:

  • By Group – permissions apply to all Users within a Group.
  • By User – permissions can be customized for specific Users.

For example, to restrict a User or a Group to only certain Workflows or Views, navigate to the Settings tab, expand the Workspace group, and select Workflows or Views. Pick the Workflow or View of interest and perform the necessary changes.

Edit workflow groups

Access to Profile Groups

Similarly, access to Profile Groups can be restricted:

  • By Group – for example, members of a specific Group can access only related profiles.
  • By User – for example, a specific User is granted access to an additional Profile Group.

Available permissions:

  • Create
  • View
  • Change status
  • Update
  • Upload
  • Start verification
  • Export profile
  • Download attachments
  • Delete

To set up permissions, navigate to the Settings tab, expand the Workspace group, and select Profile Groups. Pick the Group, select a User or Group tab, pick the entity, and select the permissions:

Group permissions

SSO

Currently the only SSO protocol supported is OAuth 2.0.

OAuth 2.0 parameters can be configured in the oauth2 section of the Platform's configuration, see the Configuration page.

Platform Portal

The Platform Portal is the built-in admin interface that enables:

  • Viewing and editing Users and their Roles
  • Managing profiles and profile groups
  • Configuring workflows and permissions
  • Visualizing data flows and analytics

API

The Platform Portal is primarily a visualization tool, while all functionality is powered by the API.

You can use the API to:

  • Manage Users and Groups
  • Work with sessions, profiles, and devices
  • Retrieve data for integration into your systems

For example, API can be used for retrieving session data by the provided session ID.

Fetching User data

Get arbitrary User

Request example: 

curl -X 'GET' \
  'https://nightly-idv.regula.app/api/security/users/<user_id>' \
  -H 'Authorization: Token <token>'

Response example:

{
  "id": "<user_id>",
  "name": "johndoe",
  "email": "johndoe@example.com",
  "active": true,
  "firstName": "John",
  "lastName": "Doe",
  "roles": [
    "verificator"
  ],
  "attributes": {},
  "external": {},  # Metadata provided by an IdP
  "type": "internal"  # Means that the user was created by the Platform, not provided externally by an IdP
}

Get current User

Request example:

curl -X 'GET' \
  'https://nightly-idv.regula.app/api/whoami' \
  -H 'Authorization: Token <token>'

Response example:

{
  "anonymous": false,
  "user": {
    "id": "<user_id>",
    "name": "Test",
    "email": "test@example.com",
    "active": true,
    "firstName": "Test name",
    "lastName": "Test last name",
    "roles": [
      "admin"
    ],
    "attributes": {},
    "external": {},
    "type": "internal"
  },
  "device": null
}

Assigning and removing Roles

Roles can be assigned to or removed from a User by sending a PATCH request to the /api/security/users/<user_id> endpoint with the roles field provided in the request body. The roles field overrides the User's current Roles.

  • To assign a Role to a User, you must provide a list of the User's current Roles along with the Role you want to assign.
  • To remove a Role from a User you must provide a list of the User's current Roles without the Role you want to remove.
curl -X 'PATCH' \
  'https://nightly-idv.regula.app/api/security/users/<user_id>' \
  -H 'Authorization: Token <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "roles": [
    "demo", "device"
  ]
}'

Allowing access to Workflow

The following request will allow you access to the Workflow with ID <workflow_id> for the Group with ID <user_group_id> and User with id <user_id>:

curl -X 'POST' \
  'https://nightly-idv.regula.app/api/workflow/<workflow_id>/access' \
  -H 'Authorization: Token <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupIds": [
    "<user_group_id>"
  ],
  "userIds": [
    "<user_id>"
  ]
}'

Allowing access to profile group

Parameter Type Description
groupId string ID of the Group.
userId string ID of the User.
permissions integer Sum of the codes (see below) of allowed permissions.

Warning

Either groupId or userId must be provided.

List of available permissions and their codes:

Permission Code
Create 1
View 2
Change status 4
Update 8
Upload 16
Start Verification 32
Export Profile 64
Download attachments 128
Delete 256

Assigning Profile Group permissions to User Group

The following request will allow you to Create, View and Update (permissions = 1 + 2 + 8 = 11) Profile Group with ID <profile_group_id> for the User Group with ID <user_group_id> :

curl -X POST 'https://nightly-idv.regula.app/api/pools/<profile_group_id>/access' \
  -H 'Authorization: Token <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupId": "<user_group_id>",
  "permissions": 11
}'

Assigning Profile Group permissions to User

The following request will allow you to Create, View and Change status (permissions = 1 + 2 + 4 = 7) for the Profile Group with ID <profile_group_id> to the User with ID <user_id>:

curl 'https://nightly-idv.regula.app/api/pools/<profile_group_id>/access' \
  -H 'Authorization: Token <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "userId": "<user_id>",
  "permissions": 7
}'