Define Permission Roles

The four built-in roles are coarse. When Editor is more than a job needs and Viewer is less, define a custom role from the permission catalog; it takes no code change and no deployment.

Before You Start

• The CLI installed and signed in — dots auth whoami should print your identity and company.
• Authority to manage roles (access.roles.manage). Attaching grants additionally needs access.grants.manage.
• Authority is additive and there is no deny rule. A role names what to include. No role can subtract a capability another role granted.

1. Read The Catalog

The catalog is the vocabulary every role and grant draws from, and it is the authority — an atom that is not in it is refused:

dots access catalog

What comes back is in two scopes, and the distinction decides where an atom can be used:

• Dotabase-scoped atoms — reading a Dotabase, creating and updating and deleting its rows, managing its views, schema, and settings, deleting it. These can go in a role or in a per-Dotabase grant.
• Workspace-scoped atoms — creating Dotabases, managing Spaces and workspace settings, using chat, managing automations, reading and writing the knowledge graph, and the access-plane atoms covering members, agents, roles, grants, approvals, and the audit ledger. These are workspace-wide and cannot be attached to a single Dotabase.

The same output shows the baseline each system role carries. To size a new role, start from the closest tier and decide what to drop.

2. Create The Role

Permissions go on as repeated --permission flags, one atom each:

dots access roles create \
  --name "Researcher" \
  --description "Reads the corpus and writes notes, no schema changes" \
  --permission dotabase.read \
  --permission dotabase.rows.create \
  --permission dotabase.rows.update \
  --permission chat.use

Two atoms are owner-reserved — workspace provisioning and cloud-sync management — and a custom role naming either is refused outright. They stay with human Owners.

Every other atom in the catalog can go in a custom role, including the access-plane atoms. A role carrying access.audit.read and nothing else is a read-only auditor.

3. Assign It

dots access assignments add --principal teammate@example.com --role Researcher

Both flags are required and take a UUID or an exact name. Principals can hold several roles at once; the result is the union of everything they carry.

There is no assignment listing — read assignments back through the principals:

dots access principals list

To take a role away:

dots access assignments remove --principal teammate@example.com --role Researcher

4. Narrow To One Dotabase With A Grant

A role applies workspace-wide. A grant attaches Dotabase-scoped atoms to exactly one Dotabase, for a role or a single principal:

dots access grants add --dotabase reading-list --subject role:Researcher --preset editor

--subject takes role:<ref> or principal:<ref>. For the permissions themselves you name either a preset or explicit atoms, and the two are mutually exclusive — giving both is an error, giving neither is an error:

dots access grants add \
  --dotabase reading-list \
  --subject role:Researcher \
  --permission dotabase.read \
  --permission dotabase.rows.create

A preset is a system role's baseline filtered down to its Dotabase-scoped atoms. --preset viewer grants dotabase.read on that one Dotabase; --preset editor adds row create, update, and delete plus view management. Use explicit atoms whenever the preset is wider than the job.

A grant carrying a workspace-scoped atom is refused. That is the enforcement of the scope split from step 1, not a lint.

Read grants back with dots access grants list, optionally filtered by --dotabase.

5. Park A Sensitive Atom Behind An Approval

Both assignments add and grants add take a repeatable --require-approval, naming atoms that should be reviewed rather than performed outright:

dots access grants add \
  --dotabase reading-list \
  --subject role:Researcher \
  --preset editor \
  --require-approval dotabase.rows.delete

Every atom you flag must be one that source actually grants; flagging something outside it is refused.

The flag combines across sources. An atom is parked only when every source contributing it is flagged. If the person also holds a role that grants row deletion plainly, the plain grant wins and nothing is parked. Approval flags narrow a path to a capability, not the capability itself.

When a flagged action does run, it is parked rather than refused: a pending request is recorded, the holders of access.approvals.decide are notified, and the caller receives a distinct "approval required" answer rather than a denial. Decide from the CLI:

dots access approvals list --status pending
dots access approvals approve <approval-id>

Approving re-checks the request against the requester's authority as it stands at decision time — an approval cannot resurrect access that was withdrawn while the request sat. Pending requests expire on their own after 72 hours.

6. Change Or Remove A Role

dots access roles update Researcher --permission dotabase.read --permission chat.use

--permission on an update replaces the whole permission set rather than adding to it. Pass the complete list you want the role to end up with, not the delta.

dots access roles delete Researcher

Both apply to custom roles only. Owner, Admin, Editor, and Viewer cannot be renamed, re-described, re-permissioned, or deleted — any attempt is refused, so their meaning stays fixed across every workspace.

Removing A Capability

There is no "may not" to write. Because the model only ever unions, removing a capability means removing every source that grants it — take the role off the principal, or narrow the role's own atom list. If the intent is to restrict one token rather than one person, that is credential scoping instead: Issue Scoped Agent Credentials covers scopes, which intersect and can only ever remove.

Confirm It Landed

dots access audit --limit 20

Role creation, assignment, grants, and approval decisions all land in the append-only ledger. Access is the map of the plane these pieces belong to; Access and Tenancy is the model in brief; Invite Your Team brings the people in that these roles apply to.