Docs

Organization Roles & Permissions

Set up multi-tenant organizations with custom roles, member management, and fine-grained access control.

12 minIntermediate

Prerequisites

  • A DUAL account
  • Organization admin access

What You'll Build

Organizations are the multi-tenant layer of DUAL — they group templates, objects, and members under shared ownership with role-based access. In this tutorial you'll create an organization, define custom roles, invite members, and configure permissions.

Step 1 — Create an Organization

Every DUAL deployment starts with an organization:

bash
curl -X POST https://blockv-labs.io/organizations \
  -H "Authorization: Bearer $DUAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": {
      "name": "Acme Rewards",
      "description": "Loyalty program tokenization",
      "metadata": {
        "industry": "retail",
        "tier": "enterprise"
      }
    }
  }'

Save the id from the response — you'll need it for all subsequent org operations.

Step 2 — Define Custom Roles

DUAL provides default roles (Owner, Admin, Member), but you can create custom roles with fine-grained permissions:

bash
curl -X POST https://blockv-labs.io/organizations/{orgId}/roles \
  -H "Authorization: Bearer $DUAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": {
      "name": "Template Designer",
      "permissions": [
        "templates.create",
        "templates.update",
        "templates.read",
        "faces.create",
        "faces.update",
        "storage.upload"
      ]
    }
  }'

Permissions follow a resource.action pattern. Common resources include templates, objects, faces, actions, webhooks, and storage.

Step 3 — Invite Members

Add team members to your organization with a specific role:

bash
curl -X POST https://blockv-labs.io/organizations/{orgId}/members \
  -H "Authorization: Bearer $DUAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "member": {
      "wallet_id": "member-wallet-address",
      "role": "Template Designer"
    }
  }'

Step 4 — List and Manage Members

View all organization members and their roles:

bash
curl https://blockv-labs.io/organizations/{orgId}/members \
  -H "Authorization: Bearer $DUAL_TOKEN"

Remove a member when needed:

bash
curl -X DELETE https://blockv-labs.io/organizations/{orgId}/members/{walletId} \
  -H "Authorization: Bearer $DUAL_TOKEN"
Best Practice: Follow the principle of least privilege — give members only the permissions they need. Use the Template Designer role for content creators and restrict objects.delete and webhooks.manage to admins.

What's Next?

With your team in place, learn to Search & Filter Objects across your growing token library.

Batch Actions & Event Bus PatternsSearch & Filter Objects