Roles & Permissions Guide
This guide describes the role-based access control (RBAC) system in the Custody Engine, including roles, permissions, and rules configuration.
Overview
The Custody Engine implements a three-tier RBAC (Role-Based Access Control) model that governs who can do what within your workspace.
Why Role-Based Access Control?
In a custody environment, precise access control is critical so only the right roles can move funds or approve transactions. It also limits who can change wallets and policies, preventing mistakes and unauthorized changes. Finally, RBAC enforces least privilege and makes audits easy by clearly linking actions to roles.
Key Principles:
- Separation of Duties: Users who create transactions shouldn't be the only ones who can approve them
- Least Privilege: Users receive only the permissions necessary for their job function
- Auditability: Every action is traceable to a user with a specific role
- Scalability: Roles can be assigned to users as they join, rather than configuring individual permissions
The model
- Roles - Define user access levels
- Rules - Specific resource + action pairs that grant access
Predefined Roles
The system provides 7 predefined role types organized into two categories. Understanding the difference between these categories is crucial for proper access control setup.
Workspace vs. Wallet Scope
┌─────────────────────────────────────────────────────────────────┐
│ WORKSPACE │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Workspace Roles can: │ │
│ │ • Create/manage users, groups, policies │ │
│ │ • Create new wallets and signers │ │
│ │ • Approve workspace-level proposals │ │
│ │ • View all workspace resources │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Wallet A │ │ Wallet B │ │ Wallet C │ │
│ │ ─────────── │ │ ─────────── │ │ ─────────── │ │
│ │ Wallet roles│ │ Wallet roles│ │ Wallet roles│ │
│ │ only apply │ │ are scoped │ │ per wallet │ │
│ │ to THIS │ │ to THIS │ │ │ │
│ │ wallet │ │ wallet │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘Workspace roles provide organization-wide permissions - managing users, creating wallets, configuring policies.
Wallet roles provide wallet-specific permissions - viewing balances, creating transactions, approving proposals for a specific wallet.
Workspace-Level Roles
| Role | Identifier | Description |
|---|---|---|
| Super Admin | super-admin | Full unrestricted access to all resources |
| Workspace Owner | workspace-owner | Owner-level workspace access with approval rights |
| Workspace Maintainer | workspace-maintainer | Maintenance of workspace resources |
| Workspace Viewer | workspace-viewer | Read-only workspace access |
Wallet-Level Roles
| Role | Identifier | Description |
|---|---|---|
| Wallet Maintainer | wallet-maintainer | Full wallet management capabilities |
| Standard Wallet User | standard-wallet-user | Standard user operations on wallets |
| Wallet Viewer | wallet-viewer | Read-only wallet access |
Role Hierarchy
Note: Higher roles include all permissions of roles below them in the hierarchy. Wallet-level roles provide access to specific wallets, while workspace-level roles provide broader organizational access.
Related Documentation
- API User Onboarding - User authentication setup
- Transaction Workflow - Policies and approvals
- Wallet Onboarding - Wallets setup