Issue Scoped Agent Credentials

An agent running on your own credential holds everything you can do, records its actions under your identity in the audit ledger, and can only be cut off by rotating the token you use yourself.

A scoped agent credential applies three narrowings in order: the agent is its own principal, that principal is granted only certain Dotabases, and the token it carries is scoped to a subset of even that.

Before You Start

• The CLI installed and signed in — dots auth whoami should print your identity and company.
• Authority to create agents (access.agents.manage). Seeding grants at creation needs access.grants.manage as well, since each seeded grant runs the same path a standalone grant does.
• A Dotabase you want the agent to work in. The examples below use one with the slug reading-list.

1. Create The Principal At Zero Authority

An agent is a principal like a person, and it is created holding nothing — no role, no grants, no implicit read of anything:

dots access agents create "Research assistant"

Zero authority is the default rather than a hardening step you can forget. Until you grant something, the principal exists and can do nothing.

2. Grant It The Dotabases It Needs

Seed the grants as you create it. A grant is <dotabase>:<preset> or <dotabase>:<comma-separated atoms>, and the flag repeats:

dots access agents create "Research assistant" --grant reading-list:editor

A preset name expands from the catalog's Dotabase-scoped baseline; an explicit atom list rides verbatim, which is what you want when a preset is wider than the job:

dots access agents create "Research assistant" --grant reading-list:dotabase.read,dotabase.rows.create

For an agent that already exists, grant separately:

dots access grants add --dotabase reading-list --subject principal:"Research assistant" --preset editor

dots access catalog prints the full vocabulary — every permission atom, which of them are Dotabase-scoped, and the baseline each system role carries. Read it before you invent an atom name; the grant is refused if the atom is not in it.

3. Issue A Narrowed Token

The credential is where the third narrowing happens. --scope restricts the token to individual permission atoms, and it repeats. Omitting it entirely issues a token carrying the principal's full authority, which for a scoped agent is rarely what you want:

dots access credentials issue \
  --principal "Research assistant" \
  --name "mcp-session" \
  --scope dotabase.read \
  --expires-at 2027-01-01T00:00:00Z

The raw token prints once. It is not stored in retrievable form and there is no command that shows it again. Put it where it is going before you close the terminal.

Scopes narrow, never widen. A scope naming an atom the principal was never granted does not confer it. The effective authority of a request is the overlap between what the principal holds and what the token allows, so an over-broad scope on a zero-authority principal is still zero authority.

--expires-at takes an ISO-8601 timestamp and is optional. Prefer setting it: an expiring token fails closed on its own if you forget it exists.

4. Read Back What Is Outstanding

dots access credentials list --principal "Research assistant"

The listing shows each credential's display prefix — never the hash and never the raw token — so you can identify one to revoke without the read itself being a leak.

5. Bound What The Agent May Do At Runtime

Grants and scopes decide what the platform will accept. An agent profile decides what the agent is offered in the first place, and it is a separate lever:

dots access profile set "Research assistant" --deny-vault-tool vault.create_row --spend-cap 5 --no-web-access

• --deny-tool and --deny-vault-tool remove named tools from what a chat turn advertises. Both deny sets are resolved when the agent is spawned and combined into the turn's denied-tool list, so a denied tool is never presented to the model.
• --spend-cap sets a daily ceiling in US dollars. When the cap blocks a call, the block itself is written to the audit ledger.
• --web-access and --no-web-access set the flag explicitly in either direction.

Read the current state back with dots access profile get "Research assistant", which also answers for an agent that has no profile yet by printing the defaults.

6. Revoke

Revocation is per credential, by id, and does not touch the principal or its grants:

dots access credentials revoke <credential-id>

The agent keeps existing and keeps its grants; the token simply stops working. To remove the authority itself rather than one token, remove the grant instead.

Confirm It Landed

Everything the principal does is attributable to it rather than to you:

dots access audit --limit 20

Filter by actor, event name, target, or time window when the ledger gets busy. Access and Tenancy explains how principals, roles, and grants resolve into an answer, and MCP Tools lists the permission atom each tool requires — which is the map you want when deciding how narrow a scope can be and still let the agent finish its job.