4. Role Management and Access Control

This tutorial explains the role-based access control (RBAC) system in the dAIEDGE Middleware, how roles work, and how they integrate with resource permissions.

Overview

dAIEDGE Middleware uses a multi-layered access control system:

1. Role-Based Access Control (RBAC): Roles grant permissions for platform operations
2. Resource Access Control: Fine-grained permissions for specific resources (hardware, datasets, AI models)
3. Blockchain Enforcement: All permissions enforced by smart contracts

Key Concepts

• Role: A named permission set (e.g., HARDWARE_OWNER_ROLE)
• Identity: A blockchain address that can be assigned roles
• Resource: Hardware, dataset, or AI model with ownership and access controls
• Access Grant: Time-limited or usage-limited permission to use a resource

Architecture

Layer 1: Role Management

Roles define what operations an identity can perform:

Identity → Has Role → Can Perform Operations

Example:

• Identity 0x742d... has HARDWARE_OWNER_ROLE
• → Can register hardware
• → Can update owned hardware

Layer 2: Resource Ownership

Resources are owned by identities:

Resource → Owned By → Identity

Example:

• Hardware hw-123 owned by 0x742d...
• → Owner has full control
• → Owner can grant access to others

Layer 3: Access Control

Resource owners can grant limited access:

Resource → Access Grant → Identity (with constraints)

Example:

• Hardware hw-123 access granted to 0x8Ba1...
• → Valid until 2025-01-01
• → Maximum 100 uses
• → Automatically revoked after expiration

System Roles

The dAIEDGE Middleware includes the following 21 roles by default.

Default Roles Overview

The admin role (or other defined admin roles) can grant/revoke child roles. By default the admin role is the only admin role for all roles.

Role Domains

System Administration: ADMIN_ROLE

Identity Management: IDENTITY_OWNER_ROLE

Resource Registration:

• Hardware: HARDWARE_OWNER_ROLE, HARDWARE_OPERATOR_ROLE
• Datasets: DATASET_OWNER_ROLE, DATASET_OPERATOR_ROLE
• AI Models: AI_MODEL_OWNER_ROLE, AI_MODEL_OPERATOR_ROLE

Access Control: ACCESS_MANAGER_ROLE, RESOURCE_OWNER_ROLE

Benchmarking: BENCHMARKING_REQUESTER, BENCHMARKING_PRODUCER

Marketplace: SELLER_ROLE, BUYER_ROLE, MARKETPLACE_OPERATOR_ROLE

Rewards: REWARD_ADMIN_ROLE, REWARD_DISTRIBUTOR_ROLE, ORACLE_ROLE

Tokens: TOKEN_ADMIN_ROLE, TOKEN_MINTER_ROLE, TOKEN_USER_ROLE

Role Operations

Prerequisites

• Completed Authentication, Wallet Management, and Identity Management tutorials
• Active session and wallet

Step 1: List All Roles

View all roles available in the system.

Endpoint

GET /api/v1/roles?page={page}

Request

curl -X GET "https://middleware-daiedge.bisite.usal.es/api/v1/roles?page=1"

async with daiedge_middleware_client.ApiClient() as api_client:
    roles_api = daiedge_middleware_client.RoleManagementApi(api_client)
    roles = await roles_api.roles_get(page=1)
    print(f"total: {roles.total}")
    for role in roles.roles:
        print(f"id: {role.id}  name: {role.name}")

Response (200 OK)

{
  "roles": [
    {
      "id": "0000019a9cb3f4e5d6c7b8a9e1f2d3c4",
      "role": "HARDWARE_OWNER_ROLE",
      "name": "Hardware owner",
      "description": "Can register and manage hardware resources",
      "uri": "https://docs.example.com/roles/hardware-owner",
      "created": 1697000000000
    },
    {
      "id": "0000019a9cc4e5f6d7c8b9a1e2f3d4c5",
      "role": "BENCHMARKING_REQUESTER",
      "name": "Benchmarking requester",
      "description": "Can request and view benchmarks",
      "uri": "https://docs.example.com/roles/benchmark-requester",
      "created": 1697000100000
    }
  ],
  "page": 1,
  "totalPages": 3,
  "total": 68
}

Response Fields

Pagination

• Default page: 1
• Page size: 25 roles per page
• Navigate: ?page=2, ?page=3, etc.

Step 2: Create Custom Role

Create a new role for your organization.

Endpoint

POST /api/v1/roles

Request

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/roles \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "0000019a9cd5f6e7d8c9b1a2e3f4d5c6",
    "password": "WalletPass123!",
    "role": "CUSTOM_OPERATOR_ROLE",
    "adminOfRoleId": "0000019a9cb3f4e5d6c7b8a9e1f2d3c4",
    "name": "Custom Operator",
    "description": "Custom role for organization operators",
    "uri": "https://myorg.example.com/roles/operator"
  }'

async with daiedge_middleware_client.ApiClient() as api_client:
    roles_api = daiedge_middleware_client.RoleManagementApi(api_client)
    result = await roles_api.roles_post(
        daiedge_middleware_client.CreateRoleBody(
            wallet_id="0000019a9cd5f6e7d8c9b1a2e3f4d5c6",
            password="WalletPass123!",
            role="CUSTOM_OPERATOR_ROLE",
            admin_of_role_id="0000019a9cb3f4e5d6c7b8a9e1f2d3c4",
            name="Custom Operator",
            description="Custom role for organization operators",
            uri="https://myorg.example.com/roles/operator",
        )
    )
    print(f"Role created: id={result.id}")

Request Body

Response (200 OK)

{
  "id": "0000019a9ce6f7e8d9c1b2a3e4f5d6c7"
}

Returns the new role’s ID.

Error Responses

Step 3: Grant Role to Identity

Assign a role to an identity (blockchain address).

Endpoint

POST /api/v1/roles/grant-role

Request

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/roles/grant-role \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "0000019a9cf7e8f9d1c2b3a4e5f6d7c8",
    "password": "WalletPass123!",
    "roleId": "0000019a9cb3f4e5d6c7b8a9e1f2d3c4",
    "did": "did:ethr:development:0x8Ba1f109551bD432803012645Ac136ddd64DBA72"
  }'

async with daiedge_middleware_client.ApiClient() as api_client:
    roles_api = daiedge_middleware_client.RoleManagementApi(api_client)
    await roles_api.roles_grant_role_post(
        daiedge_middleware_client.GranRoleBody(
            wallet_id="0000019a9cf7e8f9d1c2b3a4e5f6d7c8",
            password="WalletPass123!",
            role_id="0000019a9cb3f4e5d6c7b8a9e1f2d3c4",
            did="did:ethr:development:0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
        )
    )
    print("Role granted successfully")

Request Body

Authorization

You can only grant roles if:

• You have the admin role for this role, OR
• You are a platform administrator

Response (200 OK)

{}

Error Responses

Step 4: Revoke Role from Identity

Remove a role assignment from an identity.

Endpoint

POST /api/v1/roles/revoke-role

Request

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/roles/revoke-role \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "0000019a9d08f9e1d2c3b4a5e6f7d8c9",
    "password": "WalletPass123!",
    "roleId": "0000019a9cb3f4e5d6c7b8a9e1f2d3c4",
    "did": "did:ethr:development:0x8Ba1f109551bD432803012645Ac136ddd64DBA72"
  }'

async with daiedge_middleware_client.ApiClient() as api_client:
    roles_api = daiedge_middleware_client.RoleManagementApi(api_client)
    await roles_api.roles_revoke_role_post(
        daiedge_middleware_client.RevokeRoleBody(
            wallet_id="0000019a9d08f9e1d2c3b4a5e6f7d8c9",
            password="WalletPass123!",
            role_id="0000019a9cb3f4e5d6c7b8a9e1f2d3c4",
            did="did:ethr:development:0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
        )
    )
    print("Role revoked successfully")

Request Body

Same as Grant Role.

Response (200 OK)

{}

Error Responses

Same as Grant Role.

Step 5: Check Role Assignment

Verify if an identity has a specific role.

Endpoint

GET /api/v1/roles/has-role?roleId={roleId}&did={did}

Request

curl -X GET "https://middleware-daiedge.bisite.usal.es/api/v1/roles/has-role?roleId=0000019a9cb3f4e5d6c7b8a9e1f2d3c4&did=did:ethr:development:0x8Ba1f109551bD432803012645Ac136ddd64DBA72"

async with daiedge_middleware_client.ApiClient() as api_client:
    roles_api = daiedge_middleware_client.RoleManagementApi(api_client)
    result = await roles_api.roles_has_role_get(
        role_id="0000019a9cb3f4e5d6c7b8a9e1f2d3c4",
        did="did:ethr:development:0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
    )
    print(f"has role: {result.result}")

Response (200 OK)

{
  "result": true
}

Returns true if identity has the role, false otherwise.

Error Responses

Resource Access Control

Resource access control is independent of roles but often used together.

How It Works

1. Owner: Identity that registered the resource (automatically has access)
2. Access Grants: Owner or ACCESS_MANAGER_ROLE can grant access to others
3. Constraints: Access can have time limits, usage limits, or be indefinite

Access Control vs. Roles

Access Control Endpoints

Access control is covered in detail in:

• Hardware Access Control - Setting access constraints on hardware

Key operations:

• Grant Access: POST /api/v1/access/grant-access
• Revoke Access: POST /api/v1/access/revoke-access
• Check Access: GET /api/v1/access

Authorization Patterns

The platform uses several authorization patterns to control access to operations:

Pattern 1: Simple Role Check

Used for basic operations that only require a specific role:

Operation allowed if:
  - Identity owner matches msg.sender AND
  - Identity has required role

Used in: Hardware registration, dataset registration, AI model registration, benchmark requests

Pattern 2: Role OR Ownership

Used for access control operations where either a manager role or resource ownership grants permission:

Operation allowed if:
  - Identity owner matches msg.sender AND
  - (Identity has ACCESS_MANAGER_ROLE OR
     Identity has RESOURCE_OWNER_ROLE AND owns the resource)

Used in: Access control grant/revoke operations

Pattern 3: Role AND Ownership

Used when both a role and resource ownership are required:

Operation allowed if:
  - Identity owner matches msg.sender AND
  - Identity has required role AND
  - Identity owns the required resource

Used in: Benchmark execution (requires BENCHMARKING_PRODUCER role AND hardware ownership)

Pattern 4: Role OR Delegation

Used for update operations where either the owner or a delegated operator can perform the action:

Operation allowed if:
  - Identity owner matches msg.sender AND
  - (Identity has OWNER_ROLE AND owns resource OR
     Identity has OPERATOR_ROLE AND is delegated by resource owner)

Used in: Update operations (hardware, datasets, AI models)

Role Dependencies

Roles Requiring Additional Resources

Some roles require ownership of specific resources to be functional:

Next Steps

• Hardware Registration - Register hardware (requires roles)
• Resource Access Control - Set fine-grained access permissions
• Benchmarking - Execute benchmarks (requires benchmarking roles)

Related Topics

• Identity Management - Roles are assigned to identities
• Dataset Registration - Resource ownership and access
• AI Model Registration - Resource ownership and access