Scopes name operations, not credential holders
A credential that may read purchases cannot revoke an entitlement unless separately scoped. Anything unscoped is denied.
They are stored and enforced on your side, in the connection row. Enforced only by the caller, they would not be a limit at all.
Two checks, against two different things
The connection row records what you granted.
The token carries the single scope the current call needs — not the whole grant.
Both must agree. Which means one call is never as dangerous as the most dangerous one you allowed: a token minted to read the purchase log carries only that, and cannot be replayed against the grant route even though the same connection holds it.
Matching is exact
No prefix rule, no wildcard. payments:entitlements does not confer payments:entitlements:revoke.
Every scope declares its kind
A scope is an open string; its kind is a closed word. Each admin route that requires a scope declares a kind beside it, and the manifest carries it on every route:
| Kind | What the scope does |
|---|---|
reads | Reads, and changes nothing |
writes | Changes state inside your system |
sends | Mail or a message leaves the system |
charges | Money or an entitlement moves |
deletes | Deletes |
credentials | Mints, rotates or revokes a credential |
They are ordered from least to most restrictive, and exported as SCOPE_KINDS from core. The kind exists for a management client’s own roles. Scopes are federated: a capability adds one without touching core, so a client that maps its roles onto a list of scopes goes stale the first time one is added, and in the permissive direction. A client maps its roles onto kinds instead, and the capability that owns a scope is the one that says what it does.
- A scoped route without a kind does not compile.
Capability.adminRoutestakesAdminRouteDeclaration, which requireskindwhereverscopeis set. - A scope has exactly one kind. Holding a scope confers every route that requires it, so every route sharing one declares the same kind, and
scopeKindConflictsnames any scope whose routes disagree. - The kit’s kinds are pinned by a test. Moving an existing scope’s kind is a reviewed edit, and a new scope that is not a read is a new row.
- Absent means most restrictive.
kindis optional on the wire. A Worker that predates it sends none, and a client reads a scoped route with no kind ascredentials(scopeKindOf). A route with no scope has no kind.
The kind classifies a scope; it grants nothing. Which scopes a connection holds is still the grant on its row, and the default grant is still decided by route: a GET is a read, and so is a POST that declares both kind: "reads" and readInBody: true, a read whose input travels in its body because a URL is written to every request log — a lookup by an address, a search by a term, an export with its reason. AdminRouteDeclaration compiles readInBody only beside kind: "reads" on a POST, and readsOnly from core is the one rule the default grant and presence rooms both judge a read by. Any other POST is a write, whatever kind it declares. It also tells an agent what a tool does: pithy mcp serve leads each tool’s description with its route’s kind and sets its MCP annotations from it, so a client that asks before a destructive call asks before a charge, a delete or a credential change.
Ping needs a verified caller and no scope
It is deliberately not modeled as a scope, because granting or withholding it would change nothing: ping has to work for a connection granted nothing at all, since it is how a new key is proven before the old one is expired.
Field names are their own grant
The manifest’s privacy block, behind manifest:read, names classes and counts and never a field. GET /control-plane/privacy names every marked field and where it lives, and it sits behind privacy:read, because field names are the kind of thing you may reasonably withhold from a client that has no business seeing them. It is a read, so a connection is offered it by default, and it is separately grantable. Privacy classes is what the inventory reports.
Evidence is its own grant, and widens no other
GET /control-plane/evidence sits behind evidence:read, because the pack reads across the seam: every connection’s principal, kind, purpose and grant, and every route’s verification, together. It is a read, so a connection is offered it by default, and it is separately grantable.
Holding it confers nothing another scope guards. Migration counts stay behind migrations:read, and a capability’s health behind that capability’s own scope, secrets:status:read for the rotation count. A connection without one gets not-derivable naming the scope it lacks, never the fact. Field names stay behind privacy:read: the pack carries classes and counts. Compliance evidence is what the pack reports.
The erasure attestation is its own grant too
GET /control-plane/erasure and GET /control-plane/erasure/:subjectType/:subjectId sit behind erasure:read, because they answer across subjects: which accounts and organizations were deleted, by which kind of actor, and why. Both routes are GETs, so a connection is offered it by default, and it is separately grantable.
It never widens audit:events:read. It cites the audit events a purge recorded by id and chain position, never their IP, user-agent or metadata, and it carries nothing about a person beyond the id the lifecycle record keeps. It deletes nothing: that stays behind auth:users:delete and organization:accounts:delete. Erasure attestation is what it reports.
The record of processing is its own grant
GET /control-plane/processing sits behind processing:read, because it reads across the Worker: every processing activity, the consent counts behind each consent basis, and where each stored class sits. Its route is a GET, so a connection is offered it by default, and it is separately grantable.
It never widens another scope. The measures carry the evidence pack’s states only for a connection that also holds evidence:read, and a gap names a stored table or field only for one that also holds privacy:read; without it, a gap names the capability and the class. Record of processing is what it reports.
Reading legal holds and placing them are two grants
GET /control-plane/holds sits behind retention:read, because a hold names who counsel told you to preserve, and why. It is a read, so a connection is offered it by default, and it also opens the count of standing holds on the manifest.
POST /control-plane/holds and POST /control-plane/holds/:holdId/release sit behind retention:hold, a write, so pithy dashboard connect offers it and never grants it by default. It can only preserve: no field on either route shortens a retention, and releasing a hold returns its subject to the policy the Worker was deployed with. Holding it deletes nothing and reads no person’s data. Retention and legal holds is what a hold stops.
Listing connections and revoking one are two grants
GET /control-plane/connections and POST /control-plane/connections/lookup sit behind connections:read: every connection bound to this Worker’s environment, with its kind, purpose, authorizing principal, credential kind, grant and every trust’s subject constraint, and never key material. The lookup narrows it to one person’s, with the email in its body, because a query string is written to every request log between the client and the Worker; the listing refuses ?principal= with a 400. Both are reads, so a connection is offered the scope by default.
POST /control-plane/connections/:connectionId/revoke sits behind connections:revoke, of kind credentials, so pithy dashboard connect offers it and never grants it by default. It ends another connection’s access, every key and trust it holds, with a required reason; it refuses the calling connection, which ends through disconnect, and answers 404 for a connection bound to another environment. It is how a management client takes back what a departed person authorized. pithy dashboard connections does the same from the CLI, through the same function.
Presence adds no scope
Anyone who may read a record may see who else has it open. So a presence room kind names the scope that already reads its record, and POST /control-plane/presence/tickets is verified against that scope, the one the body’s kind names. It must be one the capability’s own admin routes require, and only reads require — GETs, and POSTs declared kind: "reads" with readInBody: true — so it is in the default grant and joining a room never takes a write. support:threads:read gates the inbox search, a POST read, and the thread room still joins with it. A kind whose scope gates a write is refused when the capability is defined.
Why grant and revoke are two scopes
They are two operations with different blast radii.
Grant mints paid product out of nothing. Revoke takes paid access from a live customer.
A refund tool needs revoke and never grant. One admin flag would make each of them the other.
The scopes capabilities define
Which of them a connection is offered by default, and how a person narrows that at the prompt, is on the dashboard’s side. Every name below is a constant of its capability — the reference is where they are enumerated.
Payments — payments:catalog:read · payments:purchases:read · payments:subscriptions:read · payments:entitlements:read · payments:discounts:read · payments:reconcile:read · payments:usage:read · payments:webhooks:read · payments:entitlements:grant · payments:entitlements:revoke · payments:overrides:set · payments:overrides:clear · payments:overrides:unrestricted · payments:discounts:create · payments:reconcile:run
payments:catalog:read is its own grant because reading what a project sells is not reading what anybody bought — it names no account and no transaction, and answers identically against an empty database. A tool that needs a list of comp-able entitlements can hold that and nothing else.
It is also what a grant is checked against: granting a key the entitlements map does not declare is refused, naming the key. A declared key no product sells is comp-only, and grantable. The same read carries what each key buys — its quotas, its features, its overrideMax ceilings, and the free floor — so an override editor is built from it alone. The read makes a good comp control possible; the refusal makes a bad one impossible.
The override writes split three ways, for the same reason grant and revoke do. payments:overrides:set pins a negotiated number or switch for one subject. payments:overrides:clear unpins one, so a tool that tidies up after a contract ends needs no power to pin. payments:overrides:unrestricted turns on every quota and every feature for one subject, for every name declared now and later. It is its own scope because it is the largest grant the kit has and the only one whose reach grows by itself: a credential that may raise one customer’s email cap cannot, by that fact, hand anybody the whole product. Tiers, quotas and features has the routes.
payments:usage:read reads the usage-reporting run log, separately from the reconciliation log’s payments:reconcile:read, because its findings name the subjects a run did not bill.
payments:webhooks:read reads the webhook-event log: every notification a store sent, whether it projected, is still pending or was abandoned, and which purchase and subscription rows it changed. It is not the purchase log’s payments:purchases:read, because the rows are a record of every customer’s commerce as the stores reported it. Neither the payload nor the store’s sentence about a failure crosses on it — the event’s type, its state and the error’s code do. Its route is a GET, so it is in the default grant.
Auth — auth:users:read · auth:devices:read · auth:sessions:revoke · auth:users:logout · auth:devices:revoke · auth:users:suspend · auth:users:delete · auth:users:export · auth:verifications:read
Ending somebody’s access and erasing them are two grants, and neither is reading them. auth:users:suspend suspends and reinstates, which can be undone. auth:users:delete deletes, restores inside the window, and starts the purge, which cannot once the window closes. auth:users:export hands over everything the kit holds about one person, a far larger disclosure than reading the user. Each gates its own routes, and every call on them is audited with the operator and the reason. Suspended and deleted accounts has the states they act on and the routes.
auth:verifications:read reads the verification ledger: every sign-in link and one-time code sent over a window, whether it was used, expired or is still waiting, and the mail job that carried it. It is not auth:users:read, because its question is whether sign-in mail lands across every account rather than who one person is, and its rows name an account by id and never by address. Its route is a GET, so it is in the default grant.
No impersonation. The most dangerous administrative capability there is, and it gets its own design and security review rather than riding in on a batch.
Organization — organization:accounts:read · organization:members:read · organization:members:write · organization:accounts:write · organization:ownership:transfer · organization:accounts:suspend · organization:accounts:delete
Two reads, because the account list is names and counts and a roster is your customers’ addresses. Holding the first confers nothing about the second. Three writes, because they are three different powers over somebody else’s account. organization:members:write is who is in it: add an existing user, remove a member, change a role, and list, resend or revoke an invitation. organization:accounts:write is what it is: its name, its short name, its seat limit. organization:ownership:transfer is who owns it, moved at once with no nomination and no acceptance — the break-glass write, and the only route that moves ownership.
Two more for the account itself, because whether it exists for its members at all is a power of its own. organization:accounts:suspend suspends an account and reinstates it; organization:accounts:delete deletes one, softly with a window or hard, and restores one inside its window. Neither implies the other, so a desk that pauses an unpaid account cannot also erase one, and neither is implied by organization:accounts:write. A suspension or a deletion reaches members’ own accounts only when the body asks, and then only those whose one organization it is. Each also gates the preview of its own cascade, which writes nothing, because who belongs to no other organization is a disclosure, and only a caller who could act on it gets it. Organization lifecycle has the routes and the cascade.
A roster write never moves the owning role, even on a connection granted all three. A token is minted for the one scope its route needs, so a roster call never carries the transfer scope: an add at the owning role, a change to or from it, or the removal of an owner is refused 403 with controlplane/insufficient_scope, naming the ownership route. The last owner gets organization/last_owner (409) instead, checked first, and it names the same route. Otherwise a roster token could add a second owner and remove the first, with no ownership-scoped call and no notice. The handler raises that refusal after the gate let the call in, and the guard records it as controlplane/call_denied all the same. Every write takes a required reason and is audited as an organization/admin_* event. Membership administration has every route and refusal.
Audit — audit:events:read · audit:events:read_detail · audit:events:export
The detail route is separate because IP, user-agent and metadata one event at a time is a forensic read, and the same fields across a hundred rows is bulk harvesting. Read-only by construction.
audit:events:read also opens the access history: every membership, connection and key change in a window, with the role or the scopes before and after. It lifts a fixed list of metadata keys and never an IP or a user-agent, so replaying who could reach the data does not take the forensic grant. It opens a connection’s usage too: which scopes it exercised and was refused, counted by key, so an access review finds the grants a connection never uses without the forensic grant either. And it opens each sink’s delivery state: every sink the trail ships to, with its host and filter, its backlog, its last delivery and its dead letters, never its token, its URL path or an event. Their routes are GETs, so it is in the default grant.
audit:events:export opens the hash chain’s verify and its export. It is its own grant because an export is the trail in bulk, every event of a tenant in a form meant to leave the building, and it confers neither of the other two. The export carries IP, user-agent and metadata values only when the connection also holds audit:events:read_detail, which is read from the connection’s grant rather than the token; otherwise it carries their salted hashes, which verify and disclose nothing. Its routes are GETs, so it is in the default grant.
Consent — consent:read. The counts of current grants, withdrawals and expired grants per purpose and notice version, the grants whose expiry has passed or falls within a window, one subject’s record with its typed and representative names opened and the merges behind it, and the signed documents and drawn signatures by their hash. The expiring list never carries a typed or representative name. Its routes are GETs, so it is in the default grant. There is no consent write scope: consent is the person’s to give and to take back, so no management credential can grant or withdraw it. Using Consent has the routes.
Email — email:jobs:read · email:jobs:retry · email:suppressions:read · email:suppressions:write · email:suppressions:delete
Support — support:threads:read · support:threads:reply · support:threads:assign · support:threads:archive · support:threads:reclassify · support:threads:flag. The read is the inbox: every thread, one thread with the sender’s linked account and purchases, and the canned replies, and it is the scope a thread’s presence room joins with. reply sends mail to a customer under your domain, which is why it is the most dangerous of the six and never rides on another. assign is its own grant beside archive, because deciding who answers a customer is not the same permission as marking them done. flag sets a viewer’s own read and snooze marks, and is the least dangerous thing here.
Leaderboard — leaderboard:entries:read · leaderboard:entries:moderate. One to look and one to act. The read is every board with the window open now, one window’s entries in the board’s own order with hidden and opted-out entries in place and unranked, and the rank-refresh lock. Its routes are GETs, so it is in the default grant. The moderate scope hides, unhides and corrects an entry and clears a stale lock, each with an idempotency key and a required reason, each recorded in the board’s moderation history and audited once; every route requiring it is a POST, so it never enters a default grant. It is not the player surface’s adminScope, which your own backend holds; a management client can never satisfy that one, so these replace it on the management routes rather than stacking with it. The leaderboard reference has the routes.
Ledger — ledger:accounts:read · ledger:transactions:read · ledger:accounts:adjust. Two reads, because a balance is a number and an entry log is every wager, payout and purchase in order. One write, and it is the one scope that moves money: it credits, debits, reverses an entry and releases a hold on one account, and reads nothing. Each write takes an idempotency key and a required reason, posts a new entry rather than editing one, never takes an account below what it has available, and writes a warning audit event. Its routes are POSTs, so it never enters a default grant. The ledger reference has the routes.
Matchmaking — matchmaking:queues:read · matchmaking:queues:moderate. One to look and one to act. The read is who is waiting: the configured games, read from config, a game’s queue, read from its queue Durable Object, its open rooms, and every pending invite. Its routes are GETs, so it is in the default grant. The moderate scope cancels a pending invite or drops a player from a game’s queue, each with an idempotency key and a required reason, and each audited once; every route requiring it is a POST, so it never enters a default grant. Neither reaches the friend graph: friend edges are the players’ own. The matchmaking reference has the routes.
Multiplayer — multiplayer:sessions:read · multiplayer:sessions:moderate. One to look and one to act. The read is the sessions in flight, from multiplayer’s index of them, one session read from its Durable Object, and the results with any void. Its routes are GETs, so it is in the default grant. Neither reads a game’s hidden state: a session read names its players, phase and deadline, never the model’s state. The moderate scope closes a session in flight with no result and voids a result, which leaderboard and rating then take back, each with an idempotency key and a required reason, and each audited once; every route requiring it is a POST, so it never enters a default grant. The multiplayer reference has the routes.
Rating — rating:players:read · rating:players:adjust. One to look and one to act. The read is every pool with its algorithm, a pool’s ratings by skill, and one player’s rating with the logged outcomes behind it. Its routes are GETs, so it is in the default grant. The adjust scope recalculates a player’s rating by replaying the outcome log, or resets it to the algorithm’s starting state, each with an idempotency key and a required reason, each recorded with the rating before and after and audited once; every route requiring it is a POST, so it never enters a default grant. It is not the player surface’s recordScope, which your own backend holds to record an outcome; neither confers the other. The rating reference has the routes.
Secrets — secrets:status:read · secrets:rotate
Media and storage — media:usage:read · storage:usage:read. What an account holds: stored records and their bytes, per organization, or per owner within one organization. Numbers only — never a record, a path or a URL.
A per-owner figure is always one organization’s. groupBy=owner and an ownerId filter are refused unless an organizationId is named — none for records written with no organization in force — because a per-user total summed across organizations would disclose that the user holds an account elsewhere, by a figure that would not reconcile with what the organization can see. The adopter’s permission hook is not asked, so it cannot widen one either.
Media, what was served — media:delivery:read. Minutes of video and image requests, per asset, in a window, read from Cloudflare’s analytics with the application’s one runtime token. It is its own grant because it is a second disclosure: usage is numbers, and this names every asset an environment serves and how much attention each one got. It is joined to the environment’s own assets, so no account total is ever reported. Its route is a GET, so it is in the default grant, and an adopter withholds it by naming the rest. Every read is audited as media/delivery_read, with counts and never a name.
Turnstile — turnstile:widgets:read. Which widget guards this environment, whether it is a real one or one of Cloudflare’s test keys, and for a real one how its challenges went in a window, read from Cloudflare’s Turnstile analytics with the application’s one runtime token and filtered by the widget’s sitekey. A test key where one belongs is reported as deliberate, and one in prod as broken. Its route is a GET, so it is in the default grant. The Turnstile reference has the four states.
Vector — vector:indexes:read. Every index the Worker’s config declares: what config declares, what Vectorize reports on the index’s own binding, how the corpus splits by embedding model, and where each one stands against the provision record. No Cloudflare API token is involved, so nothing is added to the runtime token. Namespaces are a count and never a list, because a namespace is often a tenant or organization id, and naming them would hand those ids to every holder of the scope. Its route is a GET, so it is in the default grant. The Vector reference has the shape.
Artifacts — artifacts:repos:read · artifacts:tokens:revoke. One to look and one to take a key back. The read is every repository with its owner, grants and history, and the live tokens on one with their holder where the kit recorded one, never a value. Its routes are GETs, so it is in the default grant. Revoking ends somebody’s push mid-afternoon, so it is its own scope, and an adopter who hands out the read can withhold it: it revokes one token or every live one, each with an idempotency key and a required reason, and each audited at warning. Every route requiring it is a POST, so it never enters a default grant. Neither creates, forks or deletes a repository; those stay the owner’s. Using Artifacts has the routes.
Testers — testers:roster:read · testers:roster:write · testers:nudge:send. One to look, one to change the roster, one to mail it. The read is every cohort with its roster, each tester’s activity, the forecast and the trend series. Its route is a GET, so it is in the default grant. The roster write invites an address onto a cohort, resends an invitation and takes a tester off a roster. The nudge is its own grant because mailing is the act with a blast radius outside your own systems: one testers:admin flag would let a credential issued to read a roster mail every person on it. The nudge’s cooldown is enforced in your Worker, whatever the client asks. Every route requiring either write is a POST, so neither enters a default grant.
The secrets pair is the sharpest example
Metadata only, and structurally so. The response types have no field for a value, a ciphertext, an IV, a metadata snapshot, or a rotation’s error message — so widening one is a compile error rather than a review miss.
A failed rotation reports as a status and a code, never as a message: an error message is free text written at a failure site, which is exactly where a value gets pasted by accident. The code is one of a closed set, so a reader learns why — not-recorded, not-retired — without anything a failure site wrote.
secrets:status:read is its own scope because the list of which credentials a project holds, which are stale, and which no automation will ever rotate is a map of where to push. An adopter must be able to grant a users pane without also granting that.
secrets:rotate is separate again, and folding it would have been an escalation with a name that hid it. Matching is exact, so a scope confers every route requiring it — a rotation behind secrets:status:read would have handed credential replacement to every adopter who ever wanted a status pane, retroactively and without being asked.
It never enters a default grant either, because default grants classify by route method and every route requiring it is a POST.
A capability that can write a resource must be able to read it
Payments once shipped two writes and no read, which is a subtler failure than a missing feature: a pane over a resource nothing declares computes absent and vanishes, so the surface reports that nothing is wrong.
Not blocked. Not refused. Absent — which no grant and no seed can repair, because there was no route to grant a scope to.
A refusal an adopter can act on requires a route to refuse — which is the invariant to hold onto if you are writing your own client. The invariant is now stated where the tables are defined, and a test enforces it.