Roles & Permissions

Roles define what users and API credentials can do within your Cubewire organization. The role-based access control (RBAC) system enables fine-grained permission management for security and operational efficiency.

What is a Role?

A role is a collection of permissions that determines:

• Access Level — What resources can be viewed or modified
• Operational Scope — Which actions can be performed
• Security Boundaries — What is explicitly denied

Role Types

Cubewire supports two types of roles:

System Roles

System roles are built-in and cannot be modified. They provide common access patterns for typical organizational structures.

Organization Admin

Capabilities:

• Manage users and roles
• Configure organization settings
• View audit logs and compliance reports
• Manage integrations and linked organizations

Limitations:

• Cannot perform wallet operations
• Cannot initiate transactions
• Cannot modify vault configurations

Best For: IT administrators, compliance officers, organization managers

Member

Capabilities:

• View vaults and balances
• Initiate transactions (subject to policies)
• View transaction history
• Access basic reporting

Limitations:

• Cannot manage users or roles
• Cannot modify organization settings
• Cannot change policies

Best For: Operations staff, finance team members, day-to-day operators

Viewer

Capabilities:

• View vaults and addresses
• View transaction history
• View policies and named lists
• Access read-only reports

Limitations:

• Cannot initiate any transactions
• Cannot modify any resources
• Cannot create or update anything

Best For: Auditors, external reviewers, reporting users, read-only integrations

Custom Roles

Custom roles allow you to define specific permission sets tailored to your organization's needs.

Example: Initiator

Use Case: Automated systems that only need to submit transactions, with all approvals handled by other roles.

Example: Operator

Capabilities:

• Full vault management
• Transaction initiation and monitoring
• Policy management
• Named list management

Use Case: Operations team leads who need comprehensive access without administrative privileges.

Example: Super Admin

Capabilities:

• All Organization Admin permissions
• All operational permissions
• Full API access

Use Case: Technical leads or owners who need unrestricted access.

Permission Categories

Permissions are grouped into functional categories:

Role Assignment

Users

Users can be assigned one or more roles. The effective permissions are the union of all assigned role permissions:

API Credentials

API credentials are assigned roles that determine their capabilities.

Example:

The credential inherits all permissions from its assigned role(s), just like user accounts.

Recommendation: Always start with the lowest privilege role that meets the user's needs, and only escalate when necessary.

Role Selection Guide

Best Practices

Role Design

Security

API Credentials

Related Topics

• OAuth2 Authentication — OAuth2 and API authentication
• Policies — Transaction-level controls

API Reference

For complete API documentation including endpoints for managing roles and permissions:

• List roles — GET /api/v1/roles
• Create role — POST /api/v1/roles
• List permissions — GET /api/v1/roles/permissions
• Get role — GET /api/v1/roles/{id}
• Update role — PATCH /api/v1/roles/{id}
• Delete role — DELETE /api/v1/roles/{id}
• Customize system role — PUT /api/v1/roles/{id}/customize