Querying the trail

Eight routes, and nothing else

RouteScope
GET /audit/eventsaudit:events:read
GET /audit/events/:eventIdaudit:events:read_detail
GET /audit/control-plane/access-historyaudit:events:read
GET /audit/control-plane/reachaudit:events:read
GET /audit/control-plane/usageaudit:events:read
GET /audit/control-plane/sinksaudit:events:read
GET /audit/control-plane/verifyaudit:events:export
GET /audit/control-plane/exportaudit:events:export

All eight are reads. The trail is append-only: no route deletes, edits, or prunes — because a management credential that could erase an audit row could erase the evidence of its own use. And somebody who edits the database directly is caught by the hash chain, which the last two routes verify and export. The sinks read reads no event: it answers how delivery to each SIEM sink stands, and no route adds, changes or removes one.

Two scopes, not one, because the two reads disclose different things

The listing answers who did what, when, and whether it worked. Its projection carries no network identifier and no capability payload.

The single-event read additionally returns ip, userAgent and metadata — the trail’s personal data, and the bag capabilities write email addresses and resource names into.

Bulk-harvesting those is a privacy incident, so it takes a grant the adopter makes deliberately.

And because they are separate routes: a credential holding only the detail scope cannot enumerate the trail to find ids to read, and a credential holding only the listing scope cannot resolve one.

A third scope, audit:events:export, opens the chain’s verify and its export, because an export is the trail in bulk, in a form meant to leave the building. It confers neither of the other two, and an export carries the IP, user-agent and metadata values only when the connection also holds the detail scope. Tamper evidence has why.

Scope matching is exact — no prefix, no wildcard. All three names, and what each one confers, are constants of this capability.

Pagination is keyset, never offset

The trail is appended to while it is being read. An offset page silently skips records — and on a security trail that is a record you never see, not a cosmetic glitch.

A page returns nextCursor; pass it back as ?cursor=. A malformed cursor is a first page, not an error.

The filter

Every field optional, all ANDed. An empty filter returns the whole trail, newest first.

actorType, actorIdWho acted
actorKindWhich kind of client acted — agent, dashboard or script. What actorType: "control-plane" cannot say on its own. agent also matches a user’s MCP tool calls, which run as that user
actionAn exact domain/reason code
actionPrefixEvery action under one domain. auth or auth/ matches auth/signin and auth/signout, never authority/granted. The domain is the only prefix: a reason is never matched by its start. An index range, not a scan
outcome, severity
resourceType, resourceIdWhat was targeted
project, environment, workerWhere it was recorded
tenantWhose account it was done to
from, toInclusive bounds on when

tenant: null is a filter, not an absence

This is the one field where null means something.

OmittedDo not filter by tenant
nullThe events that belong to no tenant

A CLI-originated action, a fleet-wide operator action, a row recorded before the column existed — all genuinely have no tenant, and show me those is a question adopters ask.

Without it, asking that question means writing SQL against this capability’s own table.

Who could do what, and when it changed

An auditor asks a question the listing cannot answer on its own: who could reach this data on a given date? Every change that bears on it is already in the trail — a member joining, changing role or leaving, a connection being registered, updated or removed, a key being registered or retired — but what each one changed sits in the event’s metadata, which only the single-event read returns, one event at a time, beside the IP and the user-agent.

GET /audit/control-plane/access-history?since=… answers it in one read. You get every membership, connection and key change in the window, oldest first, so you can replay them from a known state. since is required, until defaults to now, both are inclusive ISO-8601 times, and an until before since is refused rather than answered with nothing. It pages the same way the listing does, with cursor and limit: 25 changes a page by default, 100 at most.

Each change carries its eventId, occurredAt, the action it was read from, who made it — actorType, actorId and actorKind — and a subject that says which of three it is.

subjectWhat it names
memberThe organization, the membership and the member, and roleBefore and roleAfter. No before for a join, no after for a leave or a removal
connectionThe connection, its kind, purpose and principal, and scopesBefore and scopesAfter. No before for a registration, no after for a removal. A start-over’s registration names the connection it replaced in replacedConnectionId
keyThe connection and the key id, and whether it was registered, expired or revoked

Every act that changes who holds what counts, not only the member’s own. An operator adding, removing or re-roling a member, the founding of an account, which makes its founder the first member, and ownership changing hands, accepted or forced, all read as member changes. A key the CLI registered or revoked reads as a key change.

An older event reads as unknown, never as a guess. A change recorded before its emitter wrote the before and the after says detail: "not_recorded", and its missing values are null. Null there means not recorded, not none.

It needs only audit:events:read, and here is why that is safe. Each page is one SQL statement that lifts a fixed list of metadata keys out of those actions and nothing else. It never returns an IP, a user-agent, or any other metadata key, so replaying who could reach the data does not take the grant that discloses where everyone was.

It answers what this Worker’s trail holds. A management client calls it on every Worker it needs to answer for, and filters the changes by organizationId itself when it wants one account.

What one credential reached

When a key leaks, the first question is what it touched, and whose data. Every call a management credential makes is already in the trail as controlplane/call_allowed, with the scope, the key id, the method and the path it called. But those sit in metadata, so answering from the listing takes one single-event read per call, behind the grant that also discloses the IP.

GET /audit/control-plane/reach?connectionId=…&since=… answers it in one read. connectionId and since are required. keyId narrows it to the calls one key signed, or one OIDC trust admitted — a call under a trust records the trust’s id where a key id would be, beside credentialKind: "trust". until ends the window and defaults to now, and route narrows it to one route. Both bounds are inclusive ISO-8601 times, and an until before since is refused rather than answered with nothing, because nothing would read as a credential that reached nothing.

You get one row per tenant, route, action, method and outcome:

Field
tenantWhose data the calls reached, as the handler behind them recorded it. Null when it named none
route, matchedThe admin route the manifest declares that the calls matched, most specific first. A called path no route matches is its own row, with matched: false
action, method, outcomecontrolplane/call_allowed with success, or controlplane/call_denied with denied
scopeThe scope the credential carried. On a handler’s refusal it is the one the credential held, never the one it lacked. Null on the gate’s own refusal, which records only the scope the route required
count, subjectsHow many calls, and how many distinct subjects they touched. subjects is 0 for a route with no parameters, and null for an unmatched path
firstAt, lastAtThe first call and the last

subjects=true turns one route into a list of whose data. With a route, the answer adds subjects: one row per tenant and path called, with the subjectId the path names, every route parameter in params, a count, and the first and last call. The subject is the route’s last id parameter, so /accounts/:userId/:currency/transactions names the user, not the currency, and the subject count is of distinct subjects, not distinct paths. That list is what a breach scope is drawn from. subjects=true without a route is refused.

The tenant comes from the handler, joined by request id. The guard writes its row before the handler runs, so before any tenant is resolved. The handler’s own control-plane events in the same request, by the same actor, carry it. A call whose handler named no tenant, or that carries no request id, as off Cloudflare, reached no named tenant.

A refusal is one denied call. When a handler refuses a call the gate let in, it counts once, as denied, not as an admitted call beside a refusal — when the request carries a request id. Without one, the refusal still counts as denied, and the gate’s admission stays beside it. The gate’s own refusal of a verified credential counts too. A token whose signature verified but whose scope was not granted is written against its connection on its first presentation, so it is a denied row here, with scope null. A call that never verified, and a token presented again after it was spent, name no connection and are no credential’s reach.

It needs only audit:events:read. It is one SQL statement that reads the scope, the key id, the method and the path out of the call rows and the tenant out of the handler’s events, and nothing else. It never returns an IP, a user-agent or any other metadata key. The subject ids are segments of paths the credential itself sent, naming subjects the listing already shows as resourceId.

Like the access history, it answers what this Worker’s trail holds, and groups by the admin routes this Worker composes.

Which scopes a connection used

A connection granted twelve scopes that uses three holds nine it does not need, and an access review wants that number. Every call already says which scope it carried, but in metadata, so the listing cannot count them and the single-event read would take one forensic read per call.

GET /audit/control-plane/usage?since=… counts them in one read. since is required, and a missing one is refused before any query runs. connectionId names one connection; leave it out and the answer covers every connection that called in the window. until ends the window and defaults to now. Both bounds are inclusive ISO-8601 times, and an until before since is refused rather than answered with nothing, because nothing would read as an idle connection.

You get one row per scope and key the connection exercised, ordered by scope, then key:

Field
scopeThe scope exercised: the one an admitted call’s token carried, or the one a refused call required
keyIdThe registered key that signed the calls, or the OIDC trust they were admitted under. Null for a row that recorded none
allowed, deniedHow many calls were admitted, and how many refused
lastAllowedAt, lastAllowedMethod, lastAllowedPathWhen the last admitted call landed, and the method and path it called. Null when none was admitted
lastDeniedAtWhen the last refusal landed. Null when none was refused

With no connectionId, every connection answers at once. The response is a shape of its own, so a client that names a connection parses exactly what it always did. It carries since, until, oldestEventAt and connections: one entry per connection that made a call in the window, ordered by connection id, each with its connectionId and its usage rows in the shape above. Tell the two apart by their keys, connections here and connectionId with usage there. A connection that made no call in the window is absent, so join against the connection listing to find it. It is still one SQL statement, served by the call index rather than a scan of the trail.

An under-grant shows beside an over-grant. A scope the connection was refused and never allowed is a row with allowed: 0, whether the gate refused it or a handler did. A scope it holds and never exercised has no row at all, so compare the rows with the connection’s grant to find the scopes it does not use.

oldestEventAt says how far back the answer reaches. Beside the rows, it is the oldest event the trail holds, for any connection, or null on an empty trail. A window that starts before it reaches past what this trail holds, so a client can tell a quiet connection from one whose history is not here.

Only a verified refusal counts. The gate writes a refusal against the connection only when the token’s signature verified, and only on that token’s first presentation — the control-plane reference has why. A call that failed verification proves no connection, so it is in nobody’s usage.

It needs only audit:events:read. It is one SQL statement over the call rows that reads the scope, the key id, and the last admitted call’s method and path out of metadata, and nothing else. It never returns an IP, a user-agent or any other metadata key: what it returns is the management client’s own footprint.

Like the reach, it answers what this Worker’s trail holds.

Whether the trail is whole

GET /audit/control-plane/verify?tenant=… walks one tenant’s hash chain against its checkpoints and answers intact, or the first break with its event, its position and why. GET /audit/control-plane/export?tenant=… hands the chain over in canonical form, a page at a time, for pithy audit verify to check offline. tenant is required on both, and empty, ?tenant=, names the chain of events with no tenant. Tamper evidence has the chain, the checkpoints, the break reasons and the rows the chain does not cover.

The listing marks each row’s place in the chain as chainSeq, null on a row written before the chain began. A Worker older than the chain sends no chainSeq at all.

Reading is audited, including the reads that found nothing

Reading the record of everyone else’s actions is itself a security-relevant action.

audit/trail_read records the filter and how much came back. audit/event_read records which event was asked for. audit/access_history_read records the window, whether the read resumed from a cursor, and how much came back. audit/reach_read is recorded against the connection whose reach was read, with the window, the key and route it was narrowed to, whether it expanded the subjects, and how much came back. audit/usage_read is recorded once per read, with the window and how many rows came back: against the connection whose usage was read when the query named one, and otherwise against no one connection, with connectionId: null in the recorded query and connections listing every connection the answer covered. audit/chain_verified records the tenant and window walked and what was checked, and a break at critical. audit/chain_exported records the tenant and window, whether the values went out, and how many events did. The sinks read is the one with no audit/* action of its own: it reads delivery state, never the trail, so the gate’s controlplane/call_allowed row is its record.

Yes, that appends to the table it just read. A surface that exempted itself from the guarantee it provides would be worth less than the row it saves — and since the trail is kept forever unless your retention block prunes it, and controlplane/* at least a year whatever it says, a read-heavy dashboard is a growth decision as much as a security one.

It is a Kysely query first

The typed read seam is the primary interface; the listing and the single-event read are a surface over it. It is this package’s own contribution behind a scope guard, rather than something core reaches in and adds. The access history, a credential’s reach, a connection’s usage, and the chain’s verify and export are the exceptions: each is a read of its own, with no filter type, and the package’s index exports none of them.

Which means your own code can query the trail directly, with the same filter type, without going through HTTP at all — the reference has the filter’s fields and the row it returns.

ESC