Organizations — bRRAIn Docs

How organizations work in bRRAIn — the unit of billing, membership, role assignment, and Vault ownership.

Organizations

An organization is the principal unit of ownership in bRRAIn. It owns subscriptions, members, installed marketplace extensions, integrations, and the Vault that holds your team's collective memory.

You can belong to many organizations with different roles in each. A personal account can act on behalf of any organization where you have an active membership.

Creating an organization

When you first sign up you are placed in a personal workspace. To create an organization:

  1. Sign in to console.brrain.io.
  2. Click + New organization in the left sidebar.
  3. Pick a display name and a URL slug. The slug becomes part of your subdomain ({slug}.brrain.io) and appears in API URLs.
  4. Choose your data residency region. This is a one-time decision; changing region later requires a vault migration. See Data residency.
  5. Select a plan. You can start on the free tier and upgrade at any time.

After creation you become the Owner of that organization. You can transfer ownership, add additional owners, or invite members at any time.

Roles

bRRAIn uses a 7-tier role hierarchy, from highest to lowest privilege:

| Role | Can do | |---|---| | Sovereign | Everything an Owner can do plus account-level destructive actions (delete the organization, rotate the master encryption key, restore from backup). Reserved for one or two named individuals. | | Architect | Configure integrations, install marketplace extensions, change roles, edit billing. Cannot delete the organization. | | Librarian | Curate the Vault — add and rename memory zones, manage taxonomies, edit ontology entries, move records between zones. | | Operator | Day-to-day production use — write to assigned zones, create memory entries, run agents, file approvals. The most common role. | | Contributor | Limited write access to a specific zone or project. Suitable for short-term collaborators or contractors. | | Observer | Read-only across permitted zones. Cannot create, edit, or delete. | | Guest | Single-record or single-document access via a share link. No standing membership. |

Roles compose: an Architect inherits everything an Operator can do.

Inviting members

From Console → Members:

  1. Click + Invite member.
  2. Enter the email address and pick a role.
  3. Optionally restrict the member to specific zones (Operator and below).
  4. Send the invitation. The recipient gets an email with a one-time accept link valid for 14 days.
  5. The invitation status appears as Pending until they accept; you can revoke or resend at any time.

Members who already have a bRRAIn account simply add the new organization to their account. New users are walked through sign-up first, then auto-joined.

Switching organizations

Once you belong to multiple organizations:

  • From the console: the organization picker is at the top of the left sidebar.
  • From the app: the same picker appears in the user dropdown.
  • From the API or SDK: include the organization ID in your access token's scope or pass it as the X-Org-Id header.

Your view, your billing context, and your active permissions all switch with the organization.

Transferring ownership

Only a Sovereign can promote another member to Sovereign. The promotion is a two-step confirmation: the existing Sovereign requests the change, the recipient accepts via email. If you are the only Sovereign, you must promote a second one before you can step down.

Leaving an organization

From Account → Memberships, click Leave next to the organization. You forfeit all access immediately. Records you authored stay with the organization; your authorship is preserved. Owners and Sovereigns cannot leave until they have transferred or relinquished those roles to another member.

Deleting an organization

A Sovereign can request deletion under Console → Settings → Danger zone. The organization is placed in a 30-day suspended state — no API or app access, no billing, but all data is retained. You can cancel the deletion at any point during the 30 days.

After 30 days, vault data is irreversibly purged from primary storage. Encrypted backups are retained for an additional 90 days for legal hold compliance, then purged. The deletion certificate is emailed to all former Sovereigns.

Cross-organization data sharing

By design, organizations are isolated. There is no automatic data flow between them. Two patterns let organizations cooperate when needed:

  • Federation links — a Sovereign in each organization opts into a typed, scope-limited share. You can share a single zone or a single record with a sister organization.
  • bR2bR (bRRAIn-to-bRRAIn) — an open standard for cross-organization memory queries with cryptographic provenance. See the bR2bR specification.

Both patterns are auditable end-to-end. Every cross-organization read is logged on both sides.

Where to next