Actor Registration and Roles

How to onboard new actors into the DOVU OS system, manage their access, and assign them specific roles within workflows.

The DOVU OS Workflow Engine relies on actors to execute, manage, and interact with workflows. These actors are users who are assigned roles such as project owners, verifiers, or registries. The Actor Registration and Roles module provides tools to onboard and manage these users, ensuring that workflows operate smoothly and securely.

Key Features

1. Actor Registration: Create a new actor by registering them with a unique email, name, and role. This step is essential for adding users who will interact with the workflow engine.

2. Authentication: Authenticate actors via the login endpoint, enabling secure access to the system and generating authorization tokens for API requests.

3. Role Assignment: Assign specific roles to actors, determining their permissions and responsibilities within workflows.

4. Linking to Workflow Instances: Attach users to specific workflow instances, granting them access to manage or interact with specific tasks.

How It Works

• Actors are registered with a predefined role, such as supplier, verifier, or registry.

• Authentication tokens are used to ensure secure access to the system.

• Each actor can be linked to one or more workflow instances, defining their specific responsibilities.

Use Cases

• Onboarding New Users: Register project developers or verifiers to manage and approve workflow stages.

• Assigning Workflow Roles: Ensure that only authorized actors can access or modify workflows.

• Securing Access: Use authentication tokens to safeguard interactions with the API.

With these endpoints, enterprises can easily manage user access, assign roles, and integrate actors into the workflow lifecycle.

This currently is a longer running query when workflows are connected to a guardian instance, this is a piece that we will be working on to optimise the developer experience.

---

Register

The Register endpoint allows you to create a new actor within the DOVU OS system. Actors are registered with a unique name, email, password, and a predefined role (e.g., supplier, verifier, or registry). This endpoint supports onboarding new users into workflows and systems where actor-specific data or approvals are required.

POST/api/v1/register

Header parameters

Body

application/json

name*string

email*string

password*string

password_confirmation*string

role*string

Response

201422x-422:[Error] Already Registered

Body

application/json

name*string

email*string

role_id*string

updated_at*string

created_at*string

id*integer

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/register', {
    method: 'POST',
    headers: {
      "Accept": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "Test Actor",
      "email": "[email protected]",
      "password": "password",
      "password_confirmation": "password",
      "role": "supplier"
    }),
});
const data = await response.json();

Response

201422x-422:[Error] Already Registered

{
  "name": "text",
  "email": "text",
  "role_id": "text",
  "updated_at": "text",
  "created_at": "text",
  "id": 0
}

Actor Login Token

POST/api/v1/login

Header parameters

Body

application/json

email*string

password*string

Response

200401

Body

application/json

data*object

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/login', {
    method: 'POST',
    headers: {
      "Accept": "text",
      "Content-Type": "application/json",
      "Referer": "text"
    },
    body: JSON.stringify({
      "email": "{{email}}",
      "password": "{{password}}"
    }),
});
const data = await response.json();

Response

200401

{
  "data": {
    "token": "text"
  }
}

Attach user to a workflow instance

POST/api/v1/user-workflow-instances

Authorization

bearer

Header parameters

Body

application/json

workflow_instance_id*string

user_id*string

Response

201403409x-409:[Failed] Duplicated user attached to a workflow instance

Body

application/json

user_id*string

workflow_instance_id*string

updated_at*string

created_at*string

id*integer

user*object

workflow_instance*object

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/user-workflow-instances', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Accept": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "workflow_instance_id": "{{workflow_instance_id}}",
      "user_id": "6"
    }),
});
const data = await response.json();

Response

201403409x-409:[Failed] Duplicated user attached to a workflow instance

{
  "user_id": "text",
  "workflow_instance_id": "text",
  "updated_at": "text",
  "created_at": "text",
  "id": 0,
  "user": {
    "id": 0,
    "role_id": "text",
    "name": "text",
    "email": "text",
    "role": {
      "id": "text",
      "role": "text",
      "created_at": "text",
      "updated_at": "text"
    }
  },
  "workflow_instance": {
    "id": "text",
    "user_id": 0,
    "workflow_id": "text",
    "workflow_status_id": "text",
    "key": "text",
    "created_at": "text",
    "updated_at": "text",
    "workflow": {
      "id": "text",
      "name": "text",
      "description": "text",
      "key": "text",
      "workflow_integration_identities": [
        "text"
      ]
    }
  }
}