Organizations

What are Organizations?

Organizations are the top-level entity in Dual's multi-tenant architecture. Every template, object, API key, and webhook belongs to an organization. Think of an organization as an isolated project workspace, all resources within it are scoped to that organization, and members can only access resources they have been granted permission to see.

A single wallet can belong to multiple organizations, making it easy for consultants, agencies, or cross-functional teams to work across projects without creating separate accounts.

Creating an Organization

Create an organization with POST /organizations. The wallet that creates the organization is automatically assigned the Owner role:

POST /organizations
{
  "name": "Acme Corp",
  "description": "Production workspace for Acme tokenized assets"
}

The response includes the organization's unique id, which you'll use to scope all subsequent API calls.

Roles & Permissions

Every organization has a role-based access control (RBAC) system. Three default roles are provided:

• Owner, Full control including billing, member management, and organization deletion. Only one owner per organization.
• Admin, Can manage templates, objects, members, and API keys, but cannot modify billing or delete the organization.
• Member, Read access to resources plus the ability to create and manage objects.

You can create custom roles with fine-grained permissions using POST /organizations/{id}/roles. Each role has a permissions array that controls access at the resource level, for example, ["templates:read", "objects:write", "webhooks:manage"].

Update a member's role with PATCH /organizations/{id}/members/{memberId}, or remove access entirely with the corresponding DELETE endpoint.

Invitations

Invite new members by email using POST /organizations/{id}/invitations. You can optionally assign a role at invite time:

POST /organizations/org_abc/invitations
{
  "email": "alice@example.com",
  "role": "admin"
}

Invitees receive a unique link and accept the invitation via POST /organizations/invitations/{invitationId}/accept. Pending invitations can be listed with GET /organizations/{id}/invitations or revoked by admins with DELETE.

Balance & Billing

Each organization has a balance that covers platform usage fees, object emissions, action execution, and storage. Check the current balance with GET /organizations/{id}/balance and review transaction history with GET /organizations/{id}/balance/history.

Deposits are made through the MultiTokenDeposit smart contract, which accepts ETH, USDC, and DUAL tokens. See the Organizations API for the full endpoint reference.

Relationship to Other Concepts

Organizations sit at the top of the Dual resource hierarchy:

Organization
├── Members (Wallets with Roles)
├── API Keys
├── Templates
│   ├── Variations
│   └── Faces
├── Objects (instances of Templates)
├── Webhooks
└── Balance / Transactions

When you create a template, it belongs to the current organization. When an object is emitted from that template, it inherits the organization scope. Webhooks fire events scoped to the organization they're registered in.

Best Practices

• Separate environments, Keep production and development in separate organizations to avoid accidental data leakage. Templates and objects do not cross organization boundaries.
• Least privilege, Create custom roles that grant only the permissions each team member needs. Avoid assigning Admin broadly.
• Rotate API keys, Each organization's API keys should be rotated on a schedule. Use the API Keys endpoints to create and revoke keys without downtime.
• Monitor balance, Set up a webhook or periodic check on GET /organizations/{id}/balance to avoid running out of credits during high-throughput periods.