Config
| Key | Default | |
|---|---|---|
basePath | /control-plane | Where the seam mounts. Sent at registration |
replayBackend | d1 | d1 or kv. See calling from a browser |
allowedOrigins | [] | Extra browser origins allowed to call the control-plane surface. Additive to issuer, never replacing it |
corsMaxAgeSeconds | 600 | How long a browser may cache a preflight. 0 to 7200 |
The effective origin list is issuer plus allowedOrigins, deduped. They are different axes — issuer is who signed the token, an origin is where the page is — and one management client can legitimately serve pages from more than one, a staging console beside a production one. Additive means adding your own can never silently drop the one that was already working.
The hosted dashboard needs no entry. issuer already defaults to its origin, so a stock Worker answers its preflights with nothing configured.
The list gates the browser; iss still gates the token. Neither relaxes the other, and an origin here grants nothing a credential would not have had.
Set corsMaxAgeSeconds to 0 while you are working an allow-list out. The cached thing is a compile-time constant, so ten minutes normally costs nothing and saves the dashboard a round trip on every call — but a browser that has cached a refusal keeps refusing for the rest of the window after you have fixed allowedOrigins, which reads exactly like a change that did not take. Browsers cap the value themselves, so a larger number is a request rather than a guarantee.
The seam’s own routes
Shaped like every other route in the kit, and reached only by a registered connection.
| Route | Requires | Purpose |
|---|---|---|
GET /control-plane/ping | Any verified caller | Connectivity and key proof |
GET /control-plane/manifest | manifest:read | What this Worker composes, and how to call it |
GET /control-plane/keys | keys:rotate | Which keys are live, their ages and windows, every OIDC trust beside them with the claims it admits and whether it has had a first call, and who authorized the connection, its kind and its purpose |
POST /control-plane/keys | keys:rotate | Register a new key. Signed with the one it replaces |
POST /control-plane/keys/:keyId/expire | keys:rotate | Expire a superseded key. Signed with the successor |
GET /control-plane/connections | connections:read | Every connection bound to this Worker’s environment, the caller’s own among them: id, actor kind, purpose, authorizing principal, credential kind, granted scopes, every trust’s subject constraint, whether it is live, and when it was registered and revoked. It takes no query, and refuses ?principal= with a 400. No key material, no secret |
POST /control-plane/connections/lookup | connections:read | The same listing, narrowed to the connections one email authorized: { "principal": "<email>" }, compared without regard to case. The address travels in the body, never the URL |
POST /control-plane/connections/:connectionId/revoke | connections:revoke | Revoke every key and trust another connection in this environment holds, with a required reason |
GET /control-plane/migrations | migrations:read | Where each database this Worker binds stands: applied, pending, undeclared, and the run that last moved it |
GET /control-plane/privacy | privacy:read | Every stored schema holding a privacy-marked field: each field’s path, its class, and where it lives |
GET /control-plane/evidence | evidence:read | SOC 2 and ISO 27001 evidence derived from what this Worker composes and records: per control, the facts, their sources, and what could be said |
GET /control-plane/processing | processing:read | The record of processing activities, GDPR Article 30: each activity’s purpose, data classes, legal basis, recipients, retention and measures, and every gap named |
GET /control-plane/erasure | erasure:read | Every purge in a period: counts of scheduled, in progress, complete and failed, and each failed or overdue one with the step it stopped at |
GET /control-plane/erasure/:subjectType/:subjectId | erasure:read | One user’s or organization’s erasure, attested: the deletion, every step erased or kept with its reason, the state, and the audit events that record each |
GET /control-plane/holds | retention:read | Every legal hold, standing first: its subject, who placed it and why, and when, by whom and why it was released, with the count standing |
POST /control-plane/holds | retention:hold | Place a legal hold on a user, an organization or a tenant’s audit trail, with a reason |
POST /control-plane/holds/:holdId/release | retention:hold | Release a standing hold, with a reason |
POST /control-plane/presence/tickets | The room kind’s own scope | A single-use, 60-second ticket into one presence room: who else has a record open, live |
The ticket route has no scope of its own. Its body names the room kind, and the gate verifies the token against that kind’s scope, exactly as it verifies any route’s own. A token minted for any other scope is refused with controlplane/insufficient_scope and audited like any denial. An undeclared kind is a 404.
The keys listing names who sanctioned the credential. authorizedBy is the signed-in session’s email at registration, actorKind is agent, dashboard or script, and purpose is the registering operator’s words. Each is null for a connection registered before it was recorded, and absent from a Worker older than the fields, so a client parses both. purpose is untrusted text: render it escaped.
The keys listing carries the connection’s OIDC trusts too, as trusts[], revoked ones included: each trustId, issuer, audience, claims, authorizedBy, validFrom, revokedAt and firstCallAt. claims is on the face of the listing because it is the population a trust admits; authorizedBy is who sanctioned it, never who may use it. trusts is absent from a Worker older than trusts. There is no route that registers a trust, and there must not be: a workload able to add one could widen its own population. A trust is written by pithy dashboard connect --oidc-issuer, on your side, and a call made under a trust cannot register or expire a key whatever its grant — that is controlplane/key_conflict.
The connections listing is how a client finds what one person authorized. GET /control-plane/connections answers { connections, unattributed }, each oldest first: each connection as id, environment, actorKind, purpose, authorizedBy, credentialKind, scopes, trusts (each trustId, issuer, claims and revokedAt), live, registeredAt and revokedAt, and in unattributed those registered before principals were recorded. POST /control-plane/connections/lookup answers the same shape, narrowed to one principal, and the unattributed never match it. purpose is untrusted text here too. pithy dashboard connections reads through the same function, so the CLI and a client never list different things.
A person’s address never travels in a URL. A path segment or a query string is written to every request log between the client and the Worker, so the lookup is a POST with the principal in its body, and the listing’s query is strict: a client still sending ?principal= gets validation/invalid_input (400), never the whole list as though it matched. The lookup is a read all the same, declared kind: "reads" and readInBody: true, so pithy dashboard connect still offers connections:read by default. The manifest carries readInBody on the route, and a client reading a Worker older than the field sees none.
The revoke route ends another connection, never the caller’s. It takes { reason }, at most 500 characters, revokes every key and trust on the connection not yet revoked, and answers { connection, revokedKeyIds, revokedTrustIds }, both lists empty when everything was already revoked. On the calling connection it is core/conflict (409), whose action names pithy dashboard disconnect; a connection bound to another environment is core/not_found (404), as though it did not exist. Each revocation is audited at warning as controlplane/connection_revoked, with the reason, the caller’s connection, and the key and trust ids it ended. A token already minted under a revoked trust stays usable until it expires.
Error codes
Each is domain/reason, read the way every error code in the kit is.
| Code | |
|---|---|
controlplane/not_connected | No connection registered for this environment. The shipped, denying state |
controlplane/invalid_credential | One code for every failing verification step |
controlplane/insufficient_scope | Verified, and not granted this operation. Spends the token |
controlplane/key_not_found | |
controlplane/key_conflict |
controlplane/insufficient_scope can come from a handler too. A route whose gate passed can still need a grant its token was not minted for — an organization roster write that would move the owning role is refused this way, naming the ownership route. The guard records that refusal as controlplane/call_denied, with refusedBy: "handler", so a credential probing for a grant it lacks is not hidden behind the gate’s controlplane/call_allowed. That row names the credential’s scope and key id exactly as the gate’s row does, so a read of one credential’s reach finds its refusals too.
The gate’s own scope refusal names the caller, once. A call that failed verification is written with no actor and no connection, because nothing about it is proven. A call whose signature verified and whose scope was not granted is a known connection asking for something it lacks, which is what scope probing looks like. Its controlplane/call_denied row carries the token’s subject as actorId, the connection as resourceType: "controlplane_connection" and resourceId, the connection’s actorKind, and the key in metadata.keyId, beside reason, required, method and path. Only on the token’s first presentation. A signature proves who minted a token, not who presented it, and a token binds no path, so the refusal spends the token id and a token already spent is written naming nobody. A token refused for scope and presented again, even at a route it covers, is refused controlplane/invalid_credential as already spent. The body the caller receives is the same either way. A connection’s usage counts these refusals beside its admitted calls.
A call under an OIDC trust is attributed the same way, with one more refusal that names something. Its rows carry the trust’s id in metadata.keyId, beside credentialKind: "trust", on the allowed row and on both scope refusals, the gate’s and a handler’s; a key’s rows carry no credentialKind. A token whose signature, issuer and audience verified and whose claims did not match the trust’s is a genuine token for this audience, so its controlplane/call_denied row records connectionId, trustId and the claims the token actually carried as observedClaims in metadata — still with no actor. That is what lets you read the right claims off one refused run instead of guessing at them. A token that failed before those three verified records nothing about itself.
controlplane/key_expired is an audit action, not an error code. It records that a superseded key was retired — the grammar is the same and the two are not.
The manifest
{
"environment": "prod",
"connectionId": "…",
"version": "…",
"versionCreatedAt": "…",
"capabilities": [
{
"name": "payments",
"package": "@pithy-sh/payments",
"version": "1.4.0",
"healthKeys": [],
"health": null,
"configKeys": [
{ "key": "billingSubject", "choices": ["user", "organization"],
"summary": "What kind of thing holds a purchase in this project." }
],
"config": { "billingSubject": "organization" },
"adminRoutes": [
{ "method": "POST", "path": "/billing/entitlements/grant",
"scope": "payments:entitlements:grant",
"kind": "charges",
"operation": "entitlements.grant",
"summary": "Comp an entitlement, or repair a purchase that verified but never projected.",
"input": { "type": "object", "required": ["body"], "additionalProperties": false,
"properties": { "body": { "type": "object", "properties": { "…": {} } } } } }
]
}
],
"privacy": {
"declared": ["pii"], "observed": ["pii"], "counts": { "pii": 2 },
"observedNotDeclared": [], "declaredNotObserved": [],
"consoleGate": "enforced", "consoleGateReason": null,
"attestedAt": "…", "sources": ["d1", "kv"],
"retirement": { "blocked": false, "reasons": [], "liveVersions": 2 }
},
"grantedScopes": ["manifest:read", "payments:entitlements:grant"]
}Note the path. This adopter mounted payments at /billing. Each capability builds its declaration from its resolved config, so path is the fully mounted path and no client hardcodes a mount point.
operation names a route permanently. It is an id unique within its capability — entitlements.grant, users.suspend — declared by the capability beside the route. It is never derived from the path, which moves when you move a basePath, nor from the scope, which several routes share (auth:users:suspend serves suspend and reinstate). An MCP tool is named <capability>_<operation> from it, payments_entitlements_grant, so once published it does not change. pithy mcp is the client that names tools this way.
kind says what the route’s scope does: reads, writes, sends, charges, deletes or credentials, declared by the capability beside the scope, and the same on every route that shares a scope. A management client maps its own roles onto it rather than onto a list of scopes, which goes stale the first time a capability adds one. It is optional on the wire: a scoped route with no kind comes from a Worker older than kinds, and a client reads it as credentials, the most restrictive. A route with no scope has no kind. Every scope declares its kind has the vocabulary.
input is what the route takes, as JSON Schema. One object with up to three properties, path, query and body, each the schema of the validator the route runs on that part of the request. The seam generates it from the composed router — the same validator the route parses with — so it cannot drift from what the route accepts, and no capability declares it by hand. A route that validates nothing has an empty properties, which says takes nothing rather than cannot say.
operation and input are optional on the wire, like every field added to this manifest. A Worker that predates them sends neither, and a client that names tools from them offers no tool for such a route rather than guessing a name or the arguments.
Empty is a value. A capability with no management surface reports [] rather than being absent, and configKeys/config carry [] and {} rather than being omitted.
A capability that serves presence rooms lists them as presenceRooms[]: each kind, the scope a ticket into it is minted with, its activities, its participant cap, sessionTicketPath (null when the kind admits management clients only) and socketPath, built from that capability’s own basePath. A capability with none reports []. A Worker older than presence rooms sends no presenceRooms at all, which a client must not read as none.
Each capability names the package it comes from, beside the version. A version is only actionable joined against a release feed, a feed is keyed by package name, and a capability name is not one — controlplane ships inside @pithy-sh/core, so a client deriving @pithy-sh/<name> asks about a package that has never been published and is told nothing, which reads exactly like up to date. package and version are null together: the adopter’s own app capability has a name and neither. A Worker deployed before the field sends no package at all, and a client reads that as null and falls back to whatever it guessed before.
versionCreatedAt sits beside version, the deployed version’s creation time, from the same CF_VERSION_METADATA binding and under the same rule: relayed, never interpreted, and null where the binding is absent. It is there for a client that reads the body and not the headers, and for the privacy comparison below.
Migration state
GET /control-plane/migrations answers what is applied where, and whether a deploy left something behind. It asks the Worker because the Worker is the deployed build. pithy doctor reads the project on disk, which is what you have and not necessarily what is deployed.
One entry per database the Worker binds, sorted by name. A readable one carries applied, in the order the ledger applied them; pending, declared by this build and not applied, in the order they would run; undeclared, applied and not declared by this Worker; and lastGroup, the newest group with anything still applied, with its position. top means nothing is applied over it. buried names the groups and the ungrouped migrations above it.
Every migration names its namespace, which is a capability’s name, so comparing it with capabilities[] tells your own migrations from a composed capability’s. It is null only for an undeclared migration no Pithy registry could have composed.
undeclared is relative to this Worker. Two Workers bound to one D1 share its ledger, and a Worker composes only its own capabilities. From inside one, every migration the other shipped to the shared database is listed as undeclared. On a database no other Worker binds, an undeclared migration is a real corrupted chain.
A database that cannot be read says so, and costs only itself. It comes back unreadable with its name and binding and no lists at all, never empty ones, because pending: [] reads as up to date. The others still answer, and the route still answers 200.
It is read-only. Nothing over the seam runs, reverses or resets a migration.
The seam’s own manifest entry carries two counts behind the same scope, so a client sees an environment is behind on the read it already makes. pendingMigrations declares nominal: { atMost: 0 }. undeclaredMigrations declares none, because graded it would report a corrupted chain on a shared database that is fine. Both are totals across every bound database, and one database that cannot be read makes both unavailable rather than a partial total.
Privacy
GET /control-plane/privacy answers which of this Worker’s stored fields are private, which class each is, and which rest encrypted. Every D1 table and KV store the composed capabilities declare is walked, and each schema holding a marked or an encrypted field is listed: its capability, storage (d1 or kv), the database or namespace it lives in, its name, fields[] and encrypted[]. A KV field’s path leads with the part of the entry it is in: key.email, value.token, metadata.ip, value[].email for an array value.
| Key | On | What it says |
|---|---|---|
path, class | each fields[] entry | Where the marked field sits, and the class it is marked with |
encryptedAtRest | each fields[] entry | Whether that field rests encrypted. Absent where the core cannot say — an assumed class, a reference, or a core older than encrypted fields — and never defaulted to false |
unrotatable | a fields[] entry, an encrypted[] entry | true on an encrypted field whose storage is not D1. It can never be rotated, and it blocks key retirement |
encrypted[] | each schema | Every field marked encrypted at rest, classed or not, as { path } on the same paths as fields[]. Encryption can be marked without a class, so this is where an unclassed one is listed. Absent from a Worker whose core predates encrypted fields |
Read encryptedAtRest as three states, not two. true and false are answers. Absent is the core could not say, and a client that reads absent as false reports a field as plaintext when nobody checked.
It is derived from the running code, not stamped. The schemas are already in the deployed bundle, because they are the table definitions, and the walk runs on the first read and is cached for the isolate. Unmark a phi() field and it leaves this report on the next deploy, with no build step and no person in between. A Worker whose control plane is never called never walks.
Its own scope, because field names are the kind of thing you may reasonably withhold from a client that has no business seeing them. privacy:read is a read, so pithy dashboard connect preselects it, and it is separately grantable. A connection granted manifest:read alone sees the headline and no field names.
The manifest carries the headline as privacy: declared classes, observed classes, a count per class, both deltas, the console gate, which sources were walked, and retirement. What declared means, why it is an attestation, and how stale one can be is privacy classes. The privacy route’s posture carries the same block.
retirement is the field key’s retirement guard, read rather than inferred. blocked says whether a field-key version due to leave is being held live; reasons lists every reason the guard is not clean now, empty when it is; liveVersions is how many versions are live, and two — current and previous — is the normal state. A reason is unrotatable (an encrypted field rests outside D1, so nothing can prove it was re-sealed), incomplete-coverage (a schema source the guard derives from was not read) or stale (a row still holds an envelope or an index under a version due to leave). It is absent from a Worker whose core predates encrypted fields.
Evidence
GET /control-plane/evidence answers what an auditor asks for, from what the Worker already declares. It reads its own composition, routes, connections, keys, migration ledgers and privacy markers, and reports them per control. Compliance evidence is the adopter’s page; this is the shape.
| Key | On | What it says |
|---|---|---|
environment, generatedAt, version | the pack | Which environment and build answered, and when |
mappingVersion | the pack | Which version of the kit’s control table the pack follows. A reference moving, a control joining, or a rule for a state changing is a new version |
controls[] | the pack | One entry per control, always all seven, in the table’s order |
control, title | each control | A stable id a client keys on, and a title that may be reworded |
soc2, iso27001 | each control | The Trust Services Criteria and the ISO/IEC 27001:2022 Annex A references it answers |
state | each control | evidenced, gap or not-derivable. Never a verdict |
reasons | each control | What is missing, or why the Worker cannot say |
facts[] | each control | { fact, subject?, value, source }. A value is a word, a number, a flag, a list of names or null, and source names the declaration it was read from |
A control with a gap and an unknown reports gap, gaps first in reasons, and an unknown is never folded into evidenced. The response schema is exported as ControlPlaneEvidenceResponse.
Its own scope, and it never widens another. evidence:read is a read, so pithy dashboard connect preselects it. A fact another read keeps behind its own scope stays there: migration counts need migrations:read and secrets’ rotation count needs secrets:status:read, and a connection without one gets a not-derivable reason naming the scope. Field names stay GET /privacy’s, keys appear as counts and ages, and a principal is the email the connection records.
It proves controls present and performs nothing. No CLI command reads it. The hosted dashboard draws it in its Enterprise evidence pane.
Processing
GET /control-plane/processing is the record of processing activities that GDPR Article 30 asks a controller to keep, derived from what the Worker composes, declares and records. Record of processing is the adopter’s page; this is the shape.
Capabilities declare; the adopter completes. Each capability declares the activities it performs on Capability.processing: an id under its own name, a purpose, the data classes it uses, a default legal basis where it can state one, and the recipients its resolved config names. A Worker’s pithy.config.ts adds its own in a processing block, activities and overrides, parsed when the Worker assembles.
| Key | On | What it says |
|---|---|---|
environment, generatedAt, version | the record | Which environment and build answered, and when |
activities[] | the record | One entry per processing activity, the kit’s and the adopter’s |
id, purpose, declaredBy | each activity | The activity, why it happens, and the capability that declared it, or config |
classes | each activity | The privacy classes its data carries |
legalBasis, basisSource | each activity | One of the six Article 6(1) bases, or null; and capability or config, where it came from |
consent | each activity | For a consent basis: the purpose and its notice version, whether it is explicit, and the subjects who hold a grant, have withdrawn, and hold one that stands now. Else null |
recipients | each activity, the record | Who receives its data, with what they receive and source: platform, binding or declared |
retention | each activity | The class ages for its classes, and every purge window, from the resolved retention block. Null when the Worker recorded none |
measures | each activity, the record | On an activity, the evidence pack’s control ids that protect its data; on the record, each one with its references, and its current state for a connection that also holds evidence:read |
gaps | each activity, the record | What is missing. On an activity: no-legal-basis, no-consent-purpose, class-not-stored. On the record: class-unclaimed, phi-not-covered, no-standing-grant |
notDerivable | the record | What the Worker could not read on this call: the privacy inventory, the consent record, the consent catalog |
A gap is never reported as absent because its source could not be read. What could not be read is named in notDerivable. The response schema is exported as ControlPlaneProcessingResponse.
Its own scope, and it never widens another. processing:read is a read, so pithy dashboard connect preselects it. Field names stay GET /privacy’s: without privacy:read, a gap names the capability and the class, never a table or a field. It describes the processing and changes none of it. No CLI command reads it. The hosted dashboard draws it in its Enterprise evidence pane.
Erasure
GET /control-plane/erasure/:subjectType/:subjectId proves that one deletion happened, correctly; subjectType is user or organization. GET /control-plane/erasure?since&until counts every purge in a period. Erasure attestation is the adopter’s page; this is the shape.
It is read from the purge’s own record. A purge writes a row per step to the lifecycle table of the capability that owns the subject, pithy_auth_user_lifecycle or pithy_organization_lifecycle, and those rows outlive it. Every deletion of an organization goes through its lifecycle and its purge, an owner’s DELETE {base}/current included, so each has a deleted row to read; an owner’s carries actorType: "owner", and an account its sole cascade reached reads user. Each capability declares how its rows are read, as erasureRecords on the Capability contract, and @pithy-sh/audit declares auditCitations, so the seam imports neither.
| Key | On | What it says |
|---|---|---|
generatedAt, attestation | the subject read | When it was read, and the one attestation. Schema ControlPlaneErasureSubjectResponse |
subject | the attestation, a period entry | { type, id }. Nothing else about the subject |
deletion | the attestation | at, actorType, reason, mode (soft or hard), purgeAfter, and audit, its citation. mode and purgeAfter are null for a deletion recorded before #823 |
steps[] | the attestation | capability, disposition (erased or retained), reason for a retained step (the basis the capability stated, in English) with basisKey, the catalog key that translates it, summary for an erased one, completedAt, and audit. In the order each first ran, each shown once as it last finished. basisKey is null when the capability names none and absent from an older Worker |
state | the attestation, a period entry | scheduled, in_progress, complete or failed |
overdue, stoppedAt | the attestation, a period entry | Not complete two days after it came due; and the step a failed purge gave up at, or the last one an overdue purge finished, due when none has run |
completedAt, completion, failure | the attestation | When it finished, and the citations of its completion and its failure |
trail | the attestation | recorded, or absent with no audit composed, when nothing is cited |
since, until, subjects | the period read | The window, and which kinds of subject this Worker records. Schema ControlPlaneErasurePeriodResponse |
counts | the period read | scheduled, inProgress, complete, failed, and overdue counted within them |
attention[], purges[] | the period read | Every failed or overdue purge, and every purge, oldest due first |
A citation is { eventId, action, occurredAt, tenant, seq, hash }: where the event sits in its tenant’s chain, never its IP, user-agent or metadata. seq and hash are null for an event written before the chain began. The events are auth/admin_user_purge_step and organization/purge_step per step, …/purge_failed when a purge gives up, and the purge’s completion event. pithy audit verify checks the chain they point into; nothing is signed.
A purge is in a period when it came due in it, ran a step, failed or completed in it, or was still outstanding in it. until defaults to now and since to 90 days before it; a window that runs backwards or is longer than 366 days is validation/invalid_input. The period read cites nothing. A subject with no deletion in force, or a kind no composed capability records, is a 404.
Its own scope. erasure:read is a read, so pithy dashboard connect preselects it. It never widens audit:events:read: it cites an event, never its contents.
Retention and legal holds
The manifest carries retention, under manifest:read: the Worker’s retention block as it takes effect. Retention and legal holds is the adopter’s page; this is the shape. A Worker on an older core leaves it out.
| Key | What it says |
|---|---|
purgeWindows[] | Each composed soft-delete window: subject (user or organization), days, and source, policy from the block or capability from the capability’s own retention.purgeAfterDays |
audit.defaultDays | How long an event no rule names is kept, or null for forever |
audit.floorDays | The least the kit keeps controlplane/* and every lifecycle action: 365 |
audit.rules[] | Every rule, longest prefix first: prefix, days, and source, policy or floor. A floor rule is the kit holding a floored action at a year under a shorter default |
audit.floored[] | Every prefix and action the floor covers |
classAges[] | Each { class, days } the block declares, strictest first |
A hold is { id, subjectType, subjectId, reason, placedBy, placedAt, state, releasedAt, releasedBy, releaseReason }. subjectType is user, organization or audit; subjectId is null only for the untenanted audit trail; state is active or released, and the release fields are null while it stands. POST /control-plane/holds takes { subjectType, subjectId, reason } and the release takes { reason }, each reason at most 500 characters; both answer { hold }. Releasing a released hold is core/conflict (409), and an unknown id core/not_found (404). GET /control-plane/holds answers { active, holds }, standing first and newest first within each, and takes state and limit (100 by default, at most 500). Placing and releasing are audited at warning as controlplane/hold_placed and controlplane/hold_released.
Two scopes. retention:read is a read, so pithy dashboard connect preselects it, and it also opens activeHolds, the count standing, in the control plane’s own manifest entry. retention:hold is a write, offered and never granted by default.
Every scope the kit defines
| Capability | Scopes |
|---|---|
| Control plane | manifest:read · keys:rotate · connections:read · connections:revoke · migrations:read · privacy:read · evidence:read · processing:read · erasure:read · retention:read · retention:hold |
| 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 |
| 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 |
| Organization | organization:accounts:read · organization:members:read · organization:members:write · organization:accounts:write · organization:ownership:transfer · organization:accounts:suspend · organization:accounts:delete |
| Audit | audit:events:read · audit:events:read_detail · audit:events:export |
| Consent | consent:read |
email:jobs:read · email:jobs:retry · email:suppressions:read · email:suppressions:write · email:suppressions:delete | |
| Artifacts | artifacts:repos:read · artifacts:tokens:revoke |
| Leaderboard | leaderboard:entries:read · leaderboard:entries:moderate |
| Ledger | ledger:accounts:read · ledger:transactions:read · ledger:accounts:adjust |
| Matchmaking | matchmaking:queues:read · matchmaking:queues:moderate |
| Multiplayer | multiplayer:sessions:read · multiplayer:sessions:moderate |
| Rating | rating:players:read · rating:players:adjust |
| Secrets | secrets:status:read · secrets:rotate |
| Media | media:usage:read · media:delivery:read |
| Storage | storage:usage:read |
| Turnstile | turnstile:widgets:read |
| Vector | vector:indexes:read |
| Support | See the support capability |
| Testers | See the testers capability |
Matched exactly. No prefix rule, no wildcard — why each one is split the way it is is worth reading before you grant any of them.
Every scope that is not a read, by kind. Every scope the table above names and this one does not is reads.
| Kind | Scopes |
|---|---|
writes | auth:users:suspend · email:suppressions:write · leaderboard:entries:moderate · matchmaking:queues:moderate · multiplayer:sessions:moderate · organization:accounts:suspend · organization:accounts:write · organization:members:write · organization:ownership:transfer · payments:reconcile:run · rating:players:adjust · retention:hold · support:threads:archive · support:threads:assign · support:threads:flag · support:threads:reclassify · testers:roster:write |
sends | email:jobs:retry · support:threads:reply · testers:nudge:send |
charges | ledger:accounts:adjust · payments:discounts:create · payments:entitlements:grant · payments:entitlements:revoke · payments:overrides:clear · payments:overrides:set · payments:overrides:unrestricted |
deletes | auth:users:delete · email:suppressions:delete · organization:accounts:delete |
credentials | artifacts:tokens:revoke · auth:devices:revoke · auth:sessions:revoke · auth:users:logout · connections:revoke · keys:rotate · secrets:rotate |
Tables
| Table | |
|---|---|
pithy_controlplane_connections | One row per connection: the registered keys, its OIDC trusts, the issuer, the environment, and who authorized it, its kind and its purpose |
pithy_controlplane_replays | Spent token ids, keyed on the id alone, pruned after a successful claim |
pithy_controlplane_holds | One row per legal hold: its subject, who placed it, when and why, and its release. Never deleted, and kept when the person it names is purged |
What outlives a call
Two things: the token id in the replay set, and the audit event. No session, no user row, nothing on c.var.auth.
A call under an OIDC trust spends nothing. The token is the provider’s, carries no token id of ours, and serves every call in its job, so only the audit event outlives the call — and, once, the trust’s first allowed call stamped on the row, so a listing stops saying awaiting a first call. A captured token replays against this one audience until it expires, the provider’s lifetime, minutes.
The audit actor kind
control-plane, hyphenated — it names the strategy, and an enum member may carry a hyphen.
Every other namespace token is controlplane, unhyphenated, because the namespace and action patterns forbid one.
And which kind of client acted. The guard stamps the connection’s own actorKind — agent, dashboard or script — onto every control-plane event a call writes, its own and every handler’s, and onto the gate’s attributed scope refusal. The audit capability stores it and filters on it. A connection registered before kinds were recorded writes rows with none.