Skip to content

DocsEnterprise

People, roles and keys

Users and service accounts, each with API keys of their own and one or more of five roles, managed from the CLI, the REST API or the console.

Principals

  • A user is a person, named by their email. Each user takes one of the licence's seats.
  • A service account is for CI and scripts, named for what it does. It takes no seat.
  • Either holds any number of API keys and roles. Disabling one stops all its keys at once; nothing is ever deleted.

Roles

RoleMay
AdministratorDo everything, including managing people, keys and roles
ArchitectDo everything except administration
DeveloperRead everything, index repositories, run agents, record facts
ReviewerRead everything, record outcomes
Read OnlyRead

A principal may do what any of its roles grants, checked on every REST route and every MCP tool. bbm-atlas enterprise roles lists each role's permissions. The last active administrator can't be disabled or lose the role, so nobody is locked out.

Manage them from the CLI

terminal
export BBM_ATLAS_CLI_API_KEY=bbma_…        # an administrator's keybbm-atlas enterprise principals create-user ada@example.com --role developerbbm-atlas enterprise principals create-service-account ci-indexer --role developerbbm-atlas enterprise principals listbbm-atlas enterprise principals update <principal_id> --role reviewer --role developerbbm-atlas enterprise principals update <principal_id> --disablebbm-atlas enterprise keys create pipeline --principal <principal_id> --expires-in-days 90bbm-atlas enterprise keys list --principal <principal_id>bbm-atlas enterprise keys revoke <key_id> --principal <principal_id>bbm-atlas enterprise whoami                 # who this key is, its roles and permissions

Without --principal, the keys commands manage your own keys. The same operations are REST routes under /api/v1/enterprise/ and pages in the web console.

API keys

  • A key starts with bbma_ and is sent like any other: X-API-Key, or Authorization: Bearer for MCP clients.
  • It is shown once, when it is created, and stored only as a hash.
  • It may expire after a number of days, and is revoked rather than deleted, so its record stays.
  • Each key has its own rate-limit budget, when rate limiting is on: several keys of one service account, or several people behind one office address, don't share one. A key that doesn't work - mistyped, expired, revoked - counts against the address it came from.

Static keys

The keys in BBM_ATLAS_API_KEYS and BBM_ATLAS_ADMIN_API_KEYS keep working. An admin key acts as an Administrator. An ordinary key acts with BBM_ATLAS_EE_API_KEY_ROLE, Architect by default. With the identity feature nobody is anonymous: every request needs a key, a token or a session.

Where principals are kept

Principals and keys are stored where BBM-Atlas keeps repository metadata: in the local store's database, or in the Postgres database every replica shares.