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:
- 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.
- Platform system roles. Staff and integrator accounts are evaluated next (see Section 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:
| Category | Permission | Authorizes |
|---|---|---|
| Realm | realm.manage_settings | Edit Realm metadata and the Realm security policy (including the MFA policy) |
| Realm | realm.manage_billing | View and change the subscription, plan, add-ons, promo codes, and checkout |
| Realm | realm.manage_members | Manage custom roles, members, and invitations |
| Realm | realm.view_audit_logs | Read the Realm audit log and per-device logs |
| Device | device.view | View device security configuration |
| Device | device.pair | Generate, list, and revoke device pairing codes |
| Device | device.manage_config | Rename devices; arm/disarm change tracking; configure root proxy; reboot; trigger system updates |
| Device | device.remove | Unpair a device (also soft-deletes its backups) |
| Backup | backup.view | List backups and backup policies |
| Backup | backup.start_manual | Trigger a manual backup on an agent |
| Backup | backup.delete | Delete a backup archive |
| Backup Policy | backup_policy.manage | Create, edit, and delete backup schedules and retention policies |
| Restore | restore.file_level | File-level restore and live VM migration |
| Restore | restore.instant_mount | Mount and unmount backup archives |
| Restore | restore.bmr_token | Generate a Bare-Metal Recovery token |
| Vigil | vigil.view_dashboard | View Vigil statistics, history, findings, and suppression rules |
| Vigil | vigil.triage_risks | Triage, ignore, or suppress findings; create and delete suppression rules |
| Vigil | vigil.manage_policies | Edit per-device security policies |
| Vigil | vigil.start_scan | Trigger an on-demand malware or vulnerability scan |
| Crypto | crypto.rotate_keys | Initialize 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, oraudit_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
- Open Team & Roles and click Invite Member.
- Enter the user's email address and select their initial role.
- The system records the invitation and the Hermes mailer delivers an email containing a time-limited acceptance link (valid for 7 days).
- 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.