Access And Tenancy

Dots is multi-tenant. Every operation runs inside exactly one company — the tenant — and never silently reaches across tenants. Which company an operation runs in is resolved from an explicit selector (the --company flag or the x-dots-company header) among the ones you belong to, and from your credential or your session when you name none. Naming a company you are not an active member of is denied, not redirected.

The Access Plane

Within a company, authorization is governed by a small set of concepts:

• Principals — the actors: human members and AI agents alike.
• Roles — named bundles of permissions. Some are built-in system roles; you can also define custom roles.
• Grants — per-Dotabase access, so a principal can be given rights to one Dotabase without opening the whole workspace.
• Credentials — the tokens principals authenticate with, such as the personal access tokens an agent uses. A raw token is shown once, at issue.
• Entitlements — capabilities granted to a tenant, an open key space for gating features.
• Approvals — actions that are parked for review; someone with authority approves or denies them.
• Audit — an append-only ledger of who did what, queryable after the fact.

Choosing The Active Company

The selector is a company slug, and it is checked rather than trusted. A request naming a company you are not an active member of fails with a COMPANY_NOT_A_MEMBER error, and the message deliberately does not echo the slug back, so a caller probing for company names learns nothing from the refusal. There is no quiet fall-back to a company you do happen to belong to — a wrong selector is an error, never a redirect.

Leave the selector off and the default depends on how you authenticated. A request carrying a credential resolves to the principal that credential is bound to. A browser session resolves to your configured home company, and to your oldest active membership when no home company applies. On the CLI the selector itself is the first of the --company flag, the DOTS_COMPANY environment variable, or the default you recorded with dots use.

Roles, Grants, And Permissions

Every company is seeded with four system roles — Owner, Admin, Editor, and Viewer. Those four are immutable; a custom role is one you define, and it carries its own permissions.

Permissions themselves are atoms drawn from a closed catalog and written as dotted lowercase segments, such as access.roles.manage. There are no wildcards, and there are no deny rules: your authority is the additive union of the baselines your roles carry and the grants that apply to the Dotabase you are touching. Nothing you have been given can be quietly subtracted by a rule somewhere else. A small number of atoms are reserved to Owner and cannot be handed to a custom role.

A grant attaches to one Dotabase and carries permissions directly rather than naming a role. Only Dotabase-scoped permissions can be granted that way — a workspace-wide permission is rejected rather than silently narrowed — so a grant opens one Dotabase to a contractor or an agent without widening their workspace authority.

Credentials And Entitlements

A credential is a bearer token bound to one principal in one company. It is shown once at issue and stored only as a hash, so a lost token is replaced rather than recovered. A credential can also carry scopes, and those scopes are drawn from the same permission catalog: they intersect with the principal's authority and can only narrow it, never widen it.

Entitlements sit on a separate axis. A permission answers what a role may do; an entitlement answers whether the company has been provisioned some optional capability at all. The key space is open rather than a fixed list, and the gate fails closed — a capability that cannot be resolved is refused, never assumed.

Approvals And The Audit Ledger

A grant can mark some of its permissions as requiring approval. When a principal attempts one of those actions, the action is parked as a pending approval rather than performed, and the caller is told an approval is required. Anyone holding the approvals-decide permission — Owner and Admin by default — can then approve or deny it. Pending is the only non-terminal state: an approved action is replayed, landing as executed when the replay succeeds and failed when it does not, and a decision that never arrives expires on its own after 72 hours.

Everything that changes authority, and every denial, lands in the audit ledger. A record carries the actor, the event, the target, a detail payload, and a timestamp. The ledger is append-only by construction — no code path updates or deletes a record — and you read it back with dots access audit, filtering by actor, event, target, or time window.

Agents Are Principals Too

An AI agent connected over MCP is a principal with its own credential, roles, and grants, so the controls that govern people govern agents unchanged: you can give an agent read-only access, scope it to specific Dotabases, and see everything it did in the audit ledger. Connecting an agent therefore grants it a specific set of Dotabases rather than the whole workspace.