Roles and permissions

Two layers, and they are not the same

The other layer is connection scopes, enforced by your Worker rather than by us — the credential model explains why that separation exists. Organizations and teams is where a role is assigned, and the audit trail is where its use shows up.

Roles in the dashboard decide what a member of your organization may do in the UI.

Scopes on the connection decide what the credential may do against your Worker.

What each role may call

Every admin route your Worker declares names a kind: reads, writes, sends, credentials, charges or deletes. A role is the set of kinds its holder may call, read off your manifest, so a capability you compose later is governed the day it arrives.

RoleKinds it may call
memberreads
adminreads, writes, sends, credentials
ownerevery kind, adding charges and deletes

Money moving and records being deleted are the owner’s. They are the two acts the account’s signatory answers for, and the two a mistaken press cannot take back. Comping or revoking an entitlement, setting, clearing or unrestricting an allowance override, correcting a ledger, unblocking a suppressed email address, and deleting or restoring a user or an organization are each one of them.

An admin sees those acts in place, locked and marked OWNER, and pressing one says only an owner can. A member, whose role covers only reads, is shown one act: exporting everything held on one person, which your Worker declares a read, as reading that person’s record already is.

A route that declares no kind is held to deletes. The one safe assumption about a call nobody classified is that it is the worst kind there is, so a Worker too old to declare kinds gives an owner its acts and nobody else.

The same ceiling binds the agents a person authorized

An agent credential registered against your Worker records who authorized it, and the dashboard holds it to that person’s role. One holding a scope of a kind their role does not cover is marked on their member record as exceeding it. Invite your team is what happens to those agents when the person leaves or is demoted.

Scopes name operations, not people

A credential that may read purchases cannot revoke an entitlement unless separately scoped, and anything unscoped is denied.

Matching is exact. No prefix rule, no wildcard — payments:entitlements does not confer payments:entitlements:revoke.

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 is why one call is never as dangerous as the most dangerous one you allowed.

Grant and revoke are two scopes for a reason

They have 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 three that are worth withholding deliberately

audit:events:read_detail — IP, user-agent and metadata one event at a time is a forensic read; the same fields across a hundred rows is bulk harvesting.

secrets:status:read — 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. You must be able to grant a users pane without also granting that.

secrets:rotate — separate again, because matching is exact and a rotation behind the status scope would have handed credential replacement to everybody who ever wanted a status pane, retroactively and without being asked.

What no scope can grant

Reading a secret’s value. There is no route that does and no scope that could.

The reason a secret is encrypted under a key only your Worker holds is that no third party has a path to the plaintext — and a route here would be that path in every deployment, whether or not anybody granted it.

Impersonating a user. The most dangerous administrative capability there is, and it gets its own design and security review rather than riding in on a batch.

Erasing an audit row. A credential that could would be able to erase the evidence of its own use.

Every administrative action is audited

In your trail, under the control-plane actor kind, carrying the connection id and the dashboard user’s own subject — so a shared team credential still distinguishes who acted.

ESC