Users are human users or bot users who interact with the custody platform. Roles define what approval workflows and visibility those users can satisfy.
- Every user has a cryptographic key pair for authentication and signing.
- Roles determine which policies a user can participate in as maker or checker.
- You can define role names whenever you need them, but standard user-management changes assign roles through governed user intents.
- Genesis users bootstrap the environment and cannot be deleted.
- Segregation of duties prevents a single user from unilaterally completing high-risk workflows.
User and role design is the foundation of operational security. Good role design prevents single-person control, keeps approval workflows satisfiable, and gives auditors a clear record of who proposed and approved each action. Poor role design creates either dangerous concentration of power or operational dead ends where nobody can complete required approvals.
A user can:
- Propose intents.
- Approve intents.
- Reject intents.
- Review records allowed by domain read access.
Each user has:
| Field | Purpose |
|---|---|
| Identifier | Unique user ID. |
| Alias | Human-readable name, usually an email address. |
| Public key | Used for signing and authentication. |
| Roles | Determines workflow participation and visibility. |
| Domain | Defines where the user operates. |
| Lock state | Controls whether the user can act. |
A role is a named responsibility assigned to users and referenced by policies. You do not create roles as separate governed objects before use. You can introduce a role name when you reference it in users, policies, or domain read access.
| Capability | How roles affect it |
|---|---|
| Maker capability | A policy condition and first workflow step can allow a role to create an intent. |
| Checker capability | A workflow step can require approval from a role. |
| Read access | Domain permissions can allow a role to view objects such as users, accounts, policies, transactions, requests, and events. |
| Operational ownership | Roles separate platform administration, policy operations, transaction operations, compliance, audit, and automation. |
Roles are customizable. Choose role names that match your organization, then use them consistently in users, policies, and domain read access. In the standard governed user-management flow, assigning a role to a user, changing a user's roles, or removing a role from a user requires an approved v0_CreateUser or v0_UpdateUser intent.
| Role pattern | Typical use |
|---|---|
| Platform administrator | Root-domain and emergency governance. |
| Domain administrator | Domain-level administration and access management. |
| Policy operator | Policy creation and policy changes. |
| Transaction operator | Transfer or transaction creation. |
| Compliance | Screening, quarantine, and exception approval. |
| Auditor | Read-only review. |
| Bot user | Automated workflows under controlled policies. |
| Emergency operator | Breakglass or recovery workflows. |
Genesis users are created during system setup before normal governed changes can happen.
| Aspect | Genesis users | Regular users |
|---|---|---|
| Creation | Defined in genesis. | Created by v0_CreateUser intent. |
| Purpose | Bootstrap the environment. | Operate the environment after launch. |
| Deletion | Cannot be deleted. | Can be managed through governed workflows. |
| Risk | Initial root of trust. | Controlled by policies. |
Genesis users should be selected carefully and their credentials securely managed. They must be able to satisfy the first approval workflows without relying on users that do not exist yet.
Bot users enable automated operations by allowing services to authenticate and sign transactions programmatically. Use bot users for automated workflows such as scheduled transfers or integration with external systems.
A bot user:
- Authenticates using a key pair rather than interactive login.
- Performs operations automatically without human intervention.
- Requires policies configured for auto-approval to function unattended.
For the setup procedure, see Bot users.
The maker-checker model separates proposal and approval:
| Rule | Meaning |
|---|---|
| Maker is first approver | The user who submits an intent contributes the first approval. |
| No double approval | A user cannot approve the same workflow twice. |
| Quorum requires real users | A quorum of 2 requires two eligible users, not one user with the role twice. |
| Role separation | Sensitive workflows should require independent roles where appropriate. |
| Domain boundaries | Users operate within their domain and permitted descendants. |
| State | Description |
|---|---|
Unlocked | User can act according to roles and policies. |
Locked | User cannot create or approve intents. |
| Deleted | Regular user removed through a governed workflow. |
Lock users during investigations, role transitions, employment changes, or key compromise. Unlock only after the operational reason is resolved.
Users can have multiple roles, and roles can be assigned to multiple users.
This flexibility is useful, but overlapping roles must not undermine segregation of duties. If one user has many roles, policies should still require enough independent approvers. Define new role names as needed, then assign them to users through genesis, the user invitation flow, or a governed user intent.
For launch planning, see Plan your first users. For operations, see Manage users and roles. For fields and naming guidance, see User and role reference.