Access Control

Access resolves one question on every operation, before the operation runs: may this actor do this thing, here? The sections below cover each input to that answer and name the page that walks you through configuring it.

Access and Tenancy states the model compactly. Admin covers where these surfaces sit in the app, alongside the rest of workspace administration.

One Company At A Time

Every operation runs inside exactly one company — the tenant — and never quietly reaches across tenants. Which company is resolved from an explicit selector, falling back to your credential's company and then your home company. Naming a company you do not belong to is denied, not redirected: there is no path where you ask for one tenant and silently receive another.

Principals, Human And Agent

The actor is always a principal. A person who accepted an invitation is a principal; so is an AI agent connected over MCP. They are the same kind of object, so every rule below applies to both, and there is no parallel permission system for machines.

They differ in what they start with. A person arrives holding the roles their invitation named. An agent is created holding nothing at all — no role, no grants, no implicit read of anything — so every capability it ends up with was granted explicitly. Issue scoped agent credentials walks that chain end to end.

Permissions Are Atoms

Authority is expressed in small named permission atoms rather than broad tiers. Each one names a single capability, and they come in two scopes:

• Dotabase-scoped atoms answer "what may this actor do inside one Dotabase" — reading it, creating and updating and deleting rows, managing its views, its schema, its settings, deleting it. These are the atoms a per-Dotabase grant can carry.
• Workspace-scoped atoms are workspace-wide and cannot be attached to a single Dotabase — creating Dotabases, managing Spaces and workspace settings, using chat, managing automations, reading and writing the knowledge graph, and the access-plane atoms that govern members, agents, roles, grants, approvals, and the audit ledger.

A small pair of atoms is owner-reserved: workspace provisioning and cloud-sync management. They are never held by an agent and never grantable through a custom role.

Run dots access catalog to print the live vocabulary — every atom, which scope it belongs to, and the baseline each system role carries. It is the authority; a catalog addition ships as code, so read it rather than a copy of it.

Four System Roles, Strictly Nested

Every company is seeded with four built-in roles, each a strict superset of the one below:

• Viewer — the read tier: read a Dotabase, read the graph, see who the principals are, and read and write onboarding runs.
• Editor — Viewer plus authorship: create, update, and delete rows, manage views, use chat, create Dotabases, and create and update graph edges.
• Admin — every atom except the two owner-reserved.
• Owner — every atom.

System roles are immutable: they cannot be renamed, re-described, re-permissioned, or deleted, so the meaning of "Editor" does not drift out from under a workspace. When the four are not the shape you want, you build your own from atoms — Define permission roles is that path. A company always keeps at least one active human Owner; the last one cannot be removed or suspended.

Grants Narrow To One Dotabase

A role is workspace-wide. A grant is the narrow instrument: it gives a role or a single principal rights to one Dotabase, without opening the workspace. Grants carry Dotabase-scoped atoms only — that restriction is enforced, not a convention.

A preset expands a system role's baseline down to just its Dotabase-scoped atoms, so --preset editor carries Editor's authorship atoms on that one Dotabase and --preset viewer carries its read atoms. A preset and an explicit atom list are mutually exclusive on the same grant.

Credentials Narrow Further

A credential is the token a principal authenticates with. Its scopes are a pure intersection with what the principal already holds: a scope can only remove authority, never add it. Naming an atom the principal was never granted confers nothing.

The intersection is visible at the tool surface: an agent connected over MCP is offered only the tools its credential's atoms cover, so a read-scoped token is never presented with the write tools rather than being presented with them and failing.

Raw credential material is shown exactly once, at issue, and stored only as a hash.

Authority Is Additive — There Is No Deny

Roles, custom roles, and grants all union together. There is no deny rule anywhere in the model, so no precedence order needs resolving: nothing ever subtracts.

Restriction is therefore expressed by not granting, not by revoking. "Stop this role from deleting rows" is not a rule you write; it is an atom you leave out. The one narrowing mechanism in the whole plane is credential scoping, and it narrows a token, never a role.

Approvals Park An Action

An atom can be flagged as requiring approval on the assignment or grant that carries it, which produces a third outcome alongside allow and deny. The flag applies only when every source contributing that atom flags it — if a role grants it plainly, the action proceeds plainly.

When it does apply, the action is parked rather than refused: a pending approval record is written, the people who can decide are notified, and the caller gets a distinct "approval required" answer rather than a flat denial. On approval the request is re-evaluated against the requester's authority as it stands at decision time, so an approval granted after someone's access was withdrawn does not resurrect it. Pending requests expire on their own after 72 hours.

Entitlements Are A Different Axis

Roles answer "may this actor do this". An entitlement answers a separate question: "is this company provisioned for this optional capability at all". The two produce different refusals — a capability your company is not entitled to reports that specifically, rather than reporting a permission failure you would try to fix by adjusting a role.

Everything Lands In The Audit Ledger

The ledger is append-only and newest-first, filterable by actor, event, target, and time window. Denials are recorded alongside successes, so a refusal is traced by reading the ledger. Because agents are principals, an agent's actions are attributable to the agent and never blend into the record of the person who created it.

The plane fails closed. A principal whose authority cannot be resolved, or who is invited or suspended rather than active, is denied — a resolution fault never degrades into an allow.

Where To Go Next

Quickstart: Teams invites a team into a workspace, gives each role only the Dotabases it needs, and reads back who did what. Invite Your Team covers the invitation lifecycle on its own: sending an invite with its roles, handing over the one-time token, tracking who has not accepted, and revoking one. Define Permission Roles builds a role from atoms and attaches it to a single Dotabase. Issue Scoped Agent Credentials does the same job for a non-human principal.