Roles & Permissions

Tholos uses a two-level role-based access control (RBAC) system. Users have both an organization role and a vault role for each vault they belong to.

Organization roles

Organization roles determine what a user can do at the organization level:

Role	Members	Invitations	Settings	Vault access
Admin	Manage all	Create/revoke	Full control	All vaults (Manager-equivalent)
User	View	—	—	Only vaults they’re added to
Auditor	View	—	—	Read-only view of all vaults

Role hierarchy

Admin > User > Auditor

Each role inherits the permissions of roles below it. Admins can do everything Users can do, Users can do everything Auditors can do.

Key rules

• Every organization must have at least one Admin
• Admins cannot demote themselves if they are the last Admin
• Auditors automatically get Viewer access to all vaults in the organization

Vault roles

Vault roles determine what a user can do within a specific vault:

Role	View	Initiate	Approve/Reject	Manage vault
Manager	Yes	Yes	Yes	Yes
Signer	Yes	Yes	Yes	—
Initiator	Yes	Yes	—	—
Viewer	Yes	—	—	—

Role hierarchy

Manager > Signer > Initiator > Viewer

What each role can do

Viewer

• View vault details, wallets, balances, transaction history
• View policies and their status
• Export audit logs

Initiator

• Everything a Viewer can do
• Create new transactions (transfers, swaps, contract interactions)
• Propose new policies
• Submit policy edits, deactivation, and reactivation requests

Signer

• Everything an Initiator can do
• Approve or reject transactions
• Approve or reject policies and policy edits
• Participate in MPC signing ceremonies
• Delete pending/rejected policies

Manager

• Everything a Signer can do
• Add and remove vault members
• Change vault member roles
• Update vault settings
• Delete the vault

How the two levels interact

A user’s effective permissions in a vault are determined by the combination of their organization role and vault role:

Note

Organization Admins have implicit Manager-level access to all vaults in their organization, regardless of their vault role assignment.

Note

Organization Auditors have implicit Viewer-level access to all vaults, even vaults they haven’t been explicitly added to.

Scenario	Effective access
Org Admin + no vault role	Manager (implicit)
Org Admin + Vault Viewer	Manager (org role overrides)
Org User + Vault Signer	Signer
Org User + no vault role	No access to that vault
Org Auditor + no vault role	Viewer (implicit)
Org Auditor + Vault Signer	Signer

Managing roles via API

Organization roles

# Update a member's organization role
curl -X PUT https://api.tholos.app/organization/{orgId}/member/{memberId}/role \
  -H "Authorization: Bearer $THOLOS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "ADMIN"}'

Vault roles

# Update a user's vault role
curl -X PATCH https://api.tholos.app/vault/{vaultId}/user-role \
  -H "Authorization: Bearer $THOLOS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userId": 42, "role": "SIGNER"}'