DOVU Operating System
  • Welcome to DOVU OS
  • DOVU Operating System
    • The Problem
    • What is DOVU OS?
    • Core Concepts
    • Charger Protocol
    • Beyond Sustainability
  • Workflow Engine
    • The Engine
    • What to Expect Next
    • API Reference
      • Workflow Blueprints
      • Workflow Block Instance Processing
      • Actor Registration and Roles
      • Credit Warehouse Queries
      • Audit Trails
      • Schema and Data Validation
    • Tutorials and Examples
  • Template Language
    • Rationale
    • At a glance
    • Use Case: ELV Recycling
    • Language Primitives
  • DOVU Guardian Tools
    • Guardian Deployment System
    • Guardian PHP SDK
Powered by GitBook
On this page
  1. Workflow Engine
  2. API Reference

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.


PreviousWorkflow Block Instance ProcessingNextCredit Warehouse Queries

Last updated 4 months ago

  • POSTRegister
  • POSTActor Login Token
  • POSTAttach user to a workflow instance

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
namestringRequired
emailstringRequired
passwordstringRequired
password_confirmationstringRequired
rolestringRequired
Responses
201Success
application/json
422Error
application/json
x-422:[Error] Already Registered
application/json
post
POST /api/v1/register HTTP/1.1
Host: 
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
emailstringRequired
passwordstringRequired
Responses
200Success
application/json
401Error
application/json
post
POST /api/v1/login HTTP/1.1
Host: 
Accept: text
Content-Type: application/json
Referer: text
Content-Length: 47

{
  "email": "{{email}}",
  "password": "{{password}}"
}
{
  "data": {
    "token": "31|2EcNehwE41N8Th1CH7YETPQVQsFvxYiFEMoq5hSR4493b655"
  }
}

Attach user to a workflow instance

post
Authorizations
Header parameters
AcceptstringRequiredExample: application/json
Content-TypestringRequiredExample: application/json
Body
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
POST /api/v1/user-workflow-instances HTTP/1.1
Host: 
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": []
    }
  }
}