Roles & permissions — bRRAIn Docs

The full bRRAIn role hierarchy and how permissions compose across zones, records, integrations, and marketplace extensions.

Roles & permissions

Every action on bRRAIn is checked against your role and your scope. This page is the reference for who can do what.

The 7 roles

In order from highest to lowest privilege:

| # | Role | Default scope | |---|---|---| | 1 | Sovereign | Everything in the organization, including destructive account-level actions. | | 2 | Architect | Configuration, integrations, marketplace, members, billing — but not account destruction. | | 3 | Librarian | Vault curation across all zones. | | 4 | Operator | Day-to-day production work in assigned zones. | | 5 | Contributor | Limited write to specific zones or projects. | | 6 | Observer | Read-only across permitted zones. | | 7 | Guest | Single-record or single-document access via share link. |

Higher roles inherit everything lower roles can do.

Permission matrix

The matrix below shows the most-asked-about permissions. Use it as a quick reference.

Account and billing

| Action | Sovereign | Architect | Librarian | Operator | Contributor | Observer | Guest | |---|---|---|---|---|---|---|---| | View billing | ✓ | ✓ | | | | | | | Edit billing | ✓ | ✓ | | | | | | | Cancel subscription | ✓ | | | | | | | | Delete organization | ✓ | | | | | | | | Restore from backup | ✓ | | | | | | | | Rotate master key | ✓ | | | | | | |

Members and roles

| Action | Sovereign | Architect | Librarian | Operator | Contributor | Observer | Guest | |---|---|---|---|---|---|---|---| | View member list | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | Invite member | ✓ | ✓ | | | | | | | Remove member | ✓ | ✓ | | | | | | | Change role (lower than caller) | ✓ | ✓ | | | | | | | Promote to Sovereign | ✓ | | | | | | | | Demote a Sovereign | ✓ | | | | | | |

Vault

| Action | Sovereign | Architect | Librarian | Operator | Contributor | Observer | Guest | |---|---|---|---|---|---|---|---| | Browse all zones | ✓ | ✓ | ✓ | | | | | | Browse permitted zones | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | Read records in permitted zones | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (single record) | | Create records | ✓ | ✓ | ✓ | ✓ | ✓ | | | | Edit own records | ✓ | ✓ | ✓ | ✓ | ✓ | | | | Edit others' records | ✓ | ✓ | ✓ | | | | | | Delete records (soft) | ✓ | ✓ | ✓ | ✓ | | | | | Hard-delete (purge before retention) | ✓ | ✓ | | | | | | | Create or rename zones | ✓ | ✓ | ✓ | | | | | | Configure ontology | ✓ | ✓ | ✓ | | | | |

Integrations and marketplace

| Action | Sovereign | Architect | Librarian | Operator | Contributor | Observer | Guest | |---|---|---|---|---|---|---|---| | View installed extensions | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | Install marketplace extension | ✓ | ✓ | | | | | | | Update extension version | ✓ | ✓ | | | | | | | Uninstall extension | ✓ | ✓ | | | | | | | Configure OAuth credentials | ✓ | ✓ | | | | | | | Use installed extension | ✓ | ✓ | ✓ | ✓ | ✓ | | |

Compute (the brain pod)

| Action | Sovereign | Architect | Librarian | Operator | Contributor | Observer | Guest | |---|---|---|---|---|---|---|---| | Provision new pod | ✓ | ✓ | | | | | | | Restart pod | ✓ | ✓ | | | | | | | Stop pod | ✓ | ✓ | | | | | | | Upgrade pod | ✓ | ✓ | | | | | | | View pod status | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | Reset network volume | ✓ | | | | | | |

Observability and audit

| Action | Sovereign | Architect | Librarian | Operator | Contributor | Observer | Guest | |---|---|---|---|---|---|---|---| | View audit log | ✓ | ✓ | | | | | | | Export audit log | ✓ | ✓ | | | | | | | View dashboards | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |

How scopes compose

Roles are the what (what kind of action). Scopes are the where (which zone, which record, which extension).

A role assignment can be scoped:

  • Organization-wide. The default. Apply your role across every zone, every record, every extension.
  • Zone-scoped. Apply your role only in named zones. Common for Operators and Contributors. Example: "Operator in engineering zone only."
  • Project-scoped. Apply your role only in records tagged with a specific project. Common for Contributors brought in for a single deliverable.
  • Time-bounded. Apply your role only between two timestamps. Common for short-term contractors.
  • Action-bounded. Apply your role only for a specific action set. Used by automation accounts and non-human actors (see SDK: Non-human actors).

Scopes are additive. If you're a zone-scoped Operator in engineering and an organization-wide Observer, you can read everything you can see and write only in engineering.

How permission checks work

Every API call carries an authentication context. On every request the system asks four questions:

  1. Who is the caller? (resolved from the access token, session cookie, or service-account credential)
  2. What are they trying to do? (the verb on the resource — read, write, delete, etc.)
  3. Where does it touch? (which zone, record, extension, integration)
  4. Is the org policy in effect compatible with this action?

Only when all four resolve favorably does the action proceed. A failure at any step returns 403 Forbidden with a message naming which check failed (without leaking the contents of resources you're not allowed to see).

Service accounts and non-human actors

Bots, automation, robots, IoT sensors, and other non-human actors get their own identity via the SDK non-human actors feature. They're treated as first-class members with their own role assignments and audit trail. They can't be Sovereigns and can't promote anyone.

Approvals

Some actions can be configured to require human approval before they execute. Common examples:

  • Hard-delete of a record before its retention window expires.
  • Marketplace extension install in regulated organizations.
  • Cross-organization data share via federation.

When configured, the action is queued, the designated approver gets a notification, and the action runs only on approval. Approvals are themselves audit-logged.

Where to next