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

post

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.

Header parameters

AcceptstringRequiredExample: application/json

Content-TypestringRequiredExample: application/json

Body

application/json

namestringRequired

emailstringRequired

passwordstringRequired

password_confirmationstringRequired

rolestringRequired

Responses

201Success

application/json

422Error

application/json

x-422:[Error] Already Registered

application/json

post

/api/v1/register

HTTPcURLJavaScriptPython

POST /api/v1/register HTTP/1.1
Accept: text
Content-Type: application/json
Content-Length: 127

{
  "name": "Test Actor",
  "email": "[email protected]",
  "password": "password",
  "password_confirmation": "password",
  "role": "supplier"
}

{
  "name": "Test Actor",
  "email": "[email protected]",
  "role_id": "9d9d33a9-9a48-484f-aa57-cfe4207a8dde",
  "updated_at": "2024-12-06T13:30:39.000000Z",
  "created_at": "2024-12-06T13:30:39.000000Z",
  "id": 5
}

Actor Login Token

post

Header parameters

AcceptstringRequiredExample: application/json

X-XSRF-TOKENstringOptionalExample: {{xsrf-token}}

Content-TypestringRequiredExample: application/json

RefererstringRequiredExample: 127.0.0.1:8000

Body

application/json

emailstringRequired

passwordstringRequired

Responses

200Success

application/json

401Error

application/json

post

/api/v1/login

HTTPcURLJavaScriptPython

POST /api/v1/login HTTP/1.1
Accept: text
Referer: text
Content-Type: application/json
Content-Length: 47

{
  "email": "{{email}}",
  "password": "{{password}}"
}

{
  "data": {
    "token": "31|2EcNehwE41N8Th1CH7YETPQVQsFvxYiFEMoq5hSR4493b655"
  }
}

Attach user to a workflow instance

post

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

AcceptstringRequiredExample: application/json

Content-TypestringRequiredExample: application/json

Body

application/json

workflow_instance_idstringRequired

user_idstringRequired

Responses

201Success

application/json

403Error

application/json

409Error

application/json

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

application/json

post

/api/v1/user-workflow-instances

HTTPcURLJavaScriptPython

POST /api/v1/user-workflow-instances HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: text
Content-Type: application/json
Content-Length: 65

{
  "workflow_instance_id": "{{workflow_instance_id}}",
  "user_id": "6"
}

{
  "user_id": "6",
  "workflow_instance_id": "9dac9248-5559-43ae-86e0-ec1d133c2abc",
  "updated_at": "2024-12-08T08:09:57.000000Z",
  "created_at": "2024-12-08T08:09:57.000000Z",
  "id": 25,
  "user": {
    "id": 6,
    "role_id": "9dab4bbf-096f-426e-af04-af82e4a06247",
    "name": "Test Actor",
    "email": "[email protected]",
    "role": {
      "id": "9dab4bbf-096f-426e-af04-af82e4a06247",
      "role": "supplier",
      "created_at": "2024-12-07T16:52:37.000000Z",
      "updated_at": "2024-12-07T16:52:37.000000Z"
    }
  },
  "workflow_instance": {
    "id": "9dac9248-5559-43ae-86e0-ec1d133c2abc",
    "user_id": 5,
    "workflow_id": "9dab4bc0-ef1a-4b8e-aed8-dae4b0c7da8f",
    "workflow_status_id": "2",
    "key": "a8ba4c8a-002d-4564-9a8b-4cbf708440da",
    "created_at": "2024-12-08T08:05:41.000000Z",
    "updated_at": "2024-12-08T08:05:41.000000Z",
    "workflow": {
      "id": "9dab4bc0-ef1a-4b8e-aed8-dae4b0c7da8f",
      "name": "Workflow Test 1",
      "description": "Workflow Test 1",
      "key": "workflow_test",
      "workflow_integration_identities": []
    }
  }
}