Knowledge Base

Role-Based Access Control (RBAC)

Role-Based Access Control (RBAC)

In an enterprise-grade environment, blanket administrative access is an unacceptable risk. Operating a backup platform requires granular control over who can alter retention policies, who can initiate a bare-metal recovery, and who possesses the authority to manage cryptographic keys.

StateWarden enforces the Principle of Least Privilege through Role-Based Access Control (RBAC) at two levels: platform-level system roles (used by Cyberprime staff and integrators) and per-Realm roles that you define for your own team.


1. How Access Is Evaluated

Every protected API request is authorized by the WebAPI in a fixed order:

  1. Realm Owner bypass. The account stored as the Realm's owner is always authorized, regardless of any role assignment. There is exactly one Owner per Realm, and only the Owner can delete the Realm.
  2. Platform system roles. Staff and integrator accounts are evaluated next (see Section 3).
  3. Realm membership. For all other users, the WebAPI loads the member's assigned role for that Realm and evaluates its permission set. A permission is granted only when the corresponding key is explicitly set to true; a missing key means deny.

Permission checks run on every request against the current database state. If a member's role is changed or the member is removed, the new constraints apply to their existing sessions on the very next API call - there is no cached access left to expire.

2. Realm Roles and Permission Sets

Realm roles are stored per Realm as named sets of permissions. You can create any number of custom roles and assign them to members.

When a Realm is created, StateWarden automatically creates a default Administrator role holding every permission and assigns it to the Realm's creator. This default role cannot be edited or deleted; use custom roles to restrict other members.

Permission Model

Permissions are namespaced keys in the form category.action. The following keys are actively enforced by the WebAPI:

CategoryPermissionAuthorizes
Realmrealm.manage_settingsEdit Realm metadata and the Realm security policy (including the MFA policy)
Realmrealm.manage_billingView and change the subscription, plan, add-ons, promo codes, and checkout
Realmrealm.manage_membersManage custom roles, members, and invitations
Realmrealm.view_audit_logsRead the Realm audit log and per-device logs
Devicedevice.viewView device security configuration
Devicedevice.pairGenerate, list, and revoke device pairing codes
Devicedevice.manage_configRename devices; arm/disarm change tracking; configure root proxy; reboot; trigger system updates
Devicedevice.removeUnpair a device (also soft-deletes its backups)
Backupbackup.viewList backups and backup policies
Backupbackup.start_manualTrigger a manual backup on an agent
Backupbackup.deleteDelete a backup archive
Backup Policybackup_policy.manageCreate, edit, and delete backup schedules and retention policies
Restorerestore.file_levelFile-level restore and live VM migration
Restorerestore.instant_mountMount and unmount backup archives
Restorerestore.bmr_tokenGenerate a Bare-Metal Recovery token
Vigilvigil.view_dashboardView Vigil statistics, history, findings, and suppression rules
Vigilvigil.triage_risksTriage, ignore, or suppress findings; create and delete suppression rules
Vigilvigil.manage_policiesEdit per-device security policies
Vigilvigil.start_scanTrigger an on-demand malware or vulnerability scan
Cryptocrypto.rotate_keysInitialize encryption; provision device keys; rotate master and device keys

Note on Vigil suppression: suppressing or triaging a Vigil finding requires vigil.triage_risks. Read access to findings (vigil.view_dashboard) never permits suppression.

Note on destructive operations: RBAC and MFA are separate enforcement layers. Destructive or cryptographic actions (deleting backups or devices, changing policies, managing keys, restoring data) additionally require a recent MFA verification according to the Realm's MFA policy, even for users holding the correct permission. See Managing MFA and Identity: Tri-State Logic.

3. Platform System Roles

Independent of Realm roles, every account carries a platform-level system role:

  • ADMIN / SUPPORT_L3: Full read-write access across all Realms. Reserved for platform operations and advanced support.
  • SUPPORT_L1 / SUPPORT_L2: Strictly read-only. These tiers are authorized only for view-level operations (permission keys containing .view, .list, .dashboard, or audit_logs). They cannot suppress findings, modify any configuration, or perform any write operation.
  • INTEGRATOR_ADMIN: Full access, but limited to Realms belonging to their own integrator organization.
  • USER: Standard account. Access is granted exclusively through Realm membership and the assigned Realm role.

4. Managing Your Team

Team management is performed on the Team & Roles page (/members), shown in the sidebar under the active Realm's section.

Inviting a New Member

  1. Open Team & Roles and click Invite Member.
  2. Enter the user's email address and select their initial role.
  3. The system records the invitation and the Hermes mailer delivers an email containing a time-limited acceptance link (valid for 7 days).
  4. The recipient accepts the invitation at /invite/accept; membership is then created with the assigned role.

Pending invitations can be listed and revoked from the same page.

Modifying Access

Users with realm.manage_members can change a member's role or remove them from the Realm at any time. Because authorization is evaluated per request, downgraded permissions take effect on the member's next API call.

5. The Audit Trail

Every state-changing action within a Realm is written to the Realm Audit Log with the acting user's identity, a timestamp, the event type, and structured metadata. Membership and role administration, security-relevant operations, and backup operations are all recorded in the realm audit log, preserving a complete history of who changed what and when.

The WebAPI exposes no operation to modify or delete individual audit entries. The log is the system of record for compliance reviews and post-incident forensic analysis; reading it requires the realm.view_audit_logs permission.


StateWarden: Resilience Engineered.

Was this article helpful?