A connection can do exactly what its scopes say and nothing else. Your Worker enforces the row; the client is a client.
The default is every declared read
Connecting an environment is where you narrow it, the control plane capability is what enforces it, and auth is the capability whose scopes are most worth reading twice.
Plus the seam’s own two.
That default exists because of a specific failure: a connection holding only the seam’s scopes opens a dashboard where every pane says the credential does not cover this call. That looks like a broken product rather than like a grant nobody made, and the fix people reach for is granting everything.
So connecting produces a management client that can actually read, without a second command.
It is derived, never listed
Each capability declares its admin routes with the scope each one needs, and connect reads that off the Worker it is registering — the same declaration the manifest serves.
So a capability you add is offered on your next connect with no coordination and nothing to keep in step, and a capability you do not compose is never mentioned. There is no list in the CLI that could drift from the routes.
A read is a route, not a name
This is the rule that makes the default safe:
A scope joins the default only when every declared route requiring it is a GET, or a POST that declares both kind: "reads" and readInBody: true. That one exception is a read whose input travels in its body because a URL is written to every request log: looking one address up on the suppression list, the connections one person authorized, searching the users or the support inbox by a term, or exporting a user with the reason for it. Any other POST is a write.
Connect with a CLI from the release that added readInBody, or newer. An older one counts only a GET as a read, so it reads every one of those POSTs as a write and leaves the scopes they share out of the default: email:suppressions:read, connections:read, auth:users:read, auth:users:export and support:threads:read. It under-grants and never over-grants: add them with --update, or connect again with a current CLI.
Scope matching is exact — no prefixes, no wildcards — so holding a scope confers every route that requires it. One mutating route anywhere makes the whole scope a write, however it is spelled.
A scope that sounds like a read and gates one write is a write. The derivation does not read names.
One scope stays in the default despite gating writes: the key-rotation scope, which covers a key listing and two key writes. It stays because it always has, and because dropping it would break rotation on every new connection — but nothing the derivation adds can write.
Narrowing it
At a terminal, connect lists every operation your Worker exposes, described in each capability’s own words, preselected to that default. Narrowing is the point of showing you the list.
Headlessly, name what you want:
pithy dashboard connect --env prod --scope manifest:read --scope auth:users:readThe flag is repeatable, and the raw arguments are read so several survive. --scope all asks for every declared scope in one word.
An explicitly empty selection is passed through as empty, not collapsed into the default. Somebody who deselected everything must not be handed a scope anyway.
On an --update, passing no scope means leave the grant alone rather than reset it.
Why so many scopes rather than one admin flag
Because reading a user and revoking their sessions are different kinds of act.
Reading a user is a privacy operation. Revoking their sessions is an availability one. A support tool that looks people up should never also be able to sign the whole customer base out, and an incident-response tool that kills a stolen session has no business reading every address in the user table.
Auth alone declares nine, for exactly that reason.
What a narrowed grant does
Refuses every call it left out with controlplane/insufficient_scope.
And the manifest tells a client which routes those are before it tries — so a well-built management client shows a pane as unavailable rather than showing a button that fails.
Reads are audited too
Every control-plane call lands in your audit trail under its own actor kind, reads included.
Reading the user table hands a management client every customer’s email address. If only the writes were recorded, the trail would show one revoked session and say nothing about the customer list walked on the way there.
Changing your mind
--update re-points scopes on an existing connection without rebuilding it. Narrowing takes effect immediately, because your Worker reads the row on every call.
The dashboard catches up in the same command. --update ends on a signed ping, and once a ping proves the connection, the dashboard reads your Worker’s manifest and takes the grant it reports as its own copy. A change is recorded as connection/scopes_changed, with the scopes added and removed. So a grant you widen shows up without reconnecting. If the manifest cannot be read, the copy stays as it was.
A connection made before a scope existed does not hold it. Six joined the default after the first connections were made. migrations:read reads where each database stands; without it a connection gets no migration route and no migration counts on the manifest. privacy:read reads the privacy inventory, every marked field and where it lives; without it a connection gets no GET /control-plane/privacy, though the manifest’s privacy block of classes and counts still needs only manifest:read. evidence:read reads the evidence pack, SOC 2 and ISO 27001 evidence derived from what the Worker composes and records; without it a connection gets no GET /control-plane/evidence. processing:read reads the record of processing, the GDPR Article 30 record the Worker derives; without it a connection gets no GET /control-plane/processing. erasure:read reads the erasure attestation, proof of one person’s or organization’s erasure and of every purge in a period; without it a connection gets no GET /control-plane/erasure. retention:read reads the legal holds; without it a connection gets no GET /control-plane/holds and no count of standing holds on the manifest. Its write, retention:hold, is offered and never in the default. Add any of them with --update, naming every scope the connection already holds beside the new one, or with --update --scope all. Passed alone, --scope migrations:read narrows the connection to that one scope.
In the dashboard, the connection’s scope panel draws the full grant. Every scope a composed capability declares gets a row, ticked if granted and unticked if not — so a connection holding everything readable shows a list you can shorten rather than a sentence saying it holds everything and nothing to do under it. Narrowing needs no new mechanism: --update replaces the grant, so a shorter list is already a narrowing command, and the panel writes that command and nothing else. It makes no call of its own.
The seam’s own two scopes appear on every healthy connection, ticked and locked, because they are declared by the control-plane capability itself and removing them would leave a connection that cannot read its own manifest or rotate its own key. One note under the list says why, built from the rows actually drawn.
An All box above the rows ticks every one at once, or unticks them when every one is already ticked. It reads checked when all are ticked, part-filled when some are, and empty when none are. With more than one capability drawn, each capability’s list carries a box of its own, and the top box governs every list. The locked two are not its to move: they stay ticked and in the command whatever it does, and its state counts only the rows it can change.
There is no temporarily grant this — a scope is on or off, and the audit trail is what tells you what was done with it. Access reads it for you: every connection’s granted scopes beside what each one used in the last 30, 90 or 180 days as recorded, and, on Team, the command that narrows a grant to what was used.