Admin
Decide who may do what inside a workspace, and run the instance that workspace lives on.
Administering Dots covers two jobs: deciding who may do what inside a workspace, and running the instance that workspace lives on. The pages in this section cover both.
There is no separate administrator product to learn. One authorization model governs a person clicking through the app, an AI agent connected over MCP, and a script calling the API, so a decision you make in one place holds in all three.
In the app, workspace administration lives under Settings → Workspace → Access.
Every surface there also exists as a dots access command, and the command line
is the wider of the two.
Get Started
- Access ControlHow Dots decides whether an actor may perform an operation: the tenant boundary, principals covering people and agents alike, permission atoms and the four system roles, per-Dotabase grants, credential scoping, approvals, and the audit ledger.
- Access And TenancyEvery operation runs inside one company, governed by principals, roles, grants, credentials, entitlements, approvals, and an audit ledger.
- Invite Your TeamSend a workspace invitation with the roles it should land on, hand over the one-time token, track who has not accepted yet, and revoke an invite that should not be used.
- Define Permission RolesBuild a named role from permission atoms, assign it to people or agents, narrow it to a single Dotabase with a grant, and park sensitive atoms behind an approval.
- Issue Scoped Agent CredentialsGive an agent a principal of its own, grant it exactly the Dotabases it needs, and issue a token narrowed to specific permission atoms with an expiry you can revoke.
- Quickstart: Self-hosting DotsPick a hosting posture, bring the self-contained stack up, point the CLI at your own instance, and prove it answers an authenticated read.
- Self-host DotsRun Dots with one command: bundled Postgres, bundled object store, in-process identity plane, and secrets generated on first boot.
- Self-host TelemetryExport OpenTelemetry traces and metrics from a self-hosted instance to your own OTLP collector by setting one endpoint variable.
How A Request Is Authorized
Every request resolves to one principal acting in one company, and its authority is computed the same way on every surface. Dots takes the union of the principal's system-role baseline and any custom roles it holds. When the request touches a Dotabase, the grants on that join the union. Nothing in the computation takes a permission away; only what is granted counts.
A request made with a scoped credential is then narrowed: every permission outside the token's scopes is dropped, so a scope never adds authority the principal lacks. A token issued with no scopes carries its principal's full authority. A role or grant can also flag a permission as requiring approval. An action using it is parked as a pending request until a different principal holding the decide permission approves or denies it.
Key Features
- One-Company Tenancy — every operation runs inside exactly one company, named
by an explicit selector (
--companyon the CLI,x-dots-companyon the API) and checked against your memberships. - Principals Cover People And Agents — a person and an agent are the same kind of actor, so an agent's actions stay attributable to the agent rather than to whoever created it.
- Four Immutable System Roles — Owner, Admin, Editor, and Viewer are seeded into every company, each a strict superset of the one below.
- Custom Roles From Permission Atoms — when none of the four fits, build a role
from the closed catalog that
dots access catalogprints. - Additive-Only Authority — there is no deny rule anywhere in the model, so restricting a principal means granting it less.
- Per-Dotabase Grants — narrow a principal to specific Dotabases instead of the whole workspace.
- Scoped Credentials — a token carries a subset of what its principal already holds, is stored as a hash and a prefix, and is shown exactly once at issue.
- Append-Only Audit Ledger — authority changes and denials alike are recorded,
and read back with
dots access audit.
Resources
- CLI Overview — installing
dotsand how each invocation resolves its instance, its identity, and its company.