A key is not a password. It is a principal — and in a school it is a principal that can reach a child’s record.

What it is

The boundary, not the gateway

Most API-key products are gateways. They sit in front of an application, hold a policy about what each key may call, and pass the survivors through to a service that trusts whatever arrives. That design has one structural weakness, and in most industries you can live with it: everything below the gateway believes the gateway did its job.

Schools are the case where you cannot live with it. The record behind the endpoint belongs to a child, the integration asking for it was written by a vendor you did not hire, and the blast radius of a policy mistake is not a rate-limit overage — it is another school’s roster. So the wall has to sit lower than the application, and it has to still be there when the layers above it are wrong.

The wall

Closed by default, and it was not always

Every route a key may reach is named in an explicit registry that maps the route template to the scope it requires. The check runs centrally, before the handler, for every key principal:

Route absent from the registry

403 route_not_public_api. Not “not found” and not “forbidden” in the abstract — a specific, named refusal that says the route is not part of the public API at all. The entire first-party surface sits behind this by default.

Route present, scope not held

403 insufficient_scope. A distinct refusal, because “this door does not exist for keys” and “this door exists and your key lacks the grant” are different facts and an integrator debugging at 2am deserves to be told which one they hit.

Human sessions

Never consulted against the registry at all. A signed-in administrator carries full role authority through the ordinary permission system; this wall governs key principals only.

We publish the defect this replaced, because a page that only lists the wall gives no reason to believe the wall is load-bearing. The scope check used to exist as a helper that no resource route ever called. It was importable, it was tested, and it was dead. The practical effect was that a key reached every route its school allowed and its granted scopes were decorative — an export-only integration minted with a read scope could call anything its tenant could.

The fix was not to add the missing call to each route, because that design is only ever as good as the number of routes somebody remembered. It was to invert the default: enforce centrally, refuse anything unlisted, and add routes to the list deliberately. The seeded allowlist is two roster reads. That number is small on purpose and it is the honest measure of how much public API exists today.

Scopes

The whole vocabulary, including what is missing from it

These are all thirteen scopes a key may be granted. The read and write split is enforced at the vocabulary level, which is why an export-only integration cannot be mis-configured into a mutating one — the grant simply does not exist to give it.

Two absences matter more than any entry above. There is no orders:write, so no key can be minted that places an order. And there is no key-management scope of any kind, which is what makes “a key cannot mint a key” a property of the vocabulary rather than a rule somebody has to remember to check.

The three OneRoster entries are aliases rather than parallel permissions. A key minted with a specification-vocabulary scope also holds the canonical scope after expansion, which happens once at mint. The wall itself never learns about aliases, so there is exactly one place where alias logic can be wrong.

The exchange

Standard client credentials, and a throttle with a memory

If you would rather hold a short-lived token than send a long-lived secret on every call, exchange the key’s two halves for one. The grant is client_credentials, shaped to the ordinary specification: the public id is the client id, the secret half is the client secret, and what comes back is a bearer token with an explicit lifetime.

The exchanged token carries the same school pin and the same granted scopes as the key it came from, so it travels the identical context and tenancy path. That is the point of doing it this way rather than inventing a second session type: there is one tenancy mechanism, and the token is not a way around it. A key behaves identically whichever way it authenticates, and the marker that makes a principal scope-gated and rate-limited is carried through the token rather than being attached to the object that happened to be created at the header.

Repeated failures against a single client id are counted on their own throttle, separate from the general per-address limiting. The reason is specific: a secret guarded only by a per-address limit can be ground down by an attacker spread across many addresses, or by one sitting behind the same shared address as legitimate traffic. Ten failures inside a minute against one client id is enough to start refusing. A successful exchange clears the counter, so an integration that polls normally is never punished for a colleague’s typo an hour earlier.

The meter

A pure function, a chain, and an honest limit on what the chain proves

The metering brain does no input or output, touches no database, and reads no clock of its own — the caller passes the instant. That is what lets the same functions run in the enforcement path, in a usage view, in a forecast and in a test, with no divergence between what production does and what the tests check.

A refused call costs nothing

The gate reads the period total, decides, and records only on the allowed path. A call rejected for quota is never itself counted. The first denied call of a period is the one that arrives exactly at the cap.

Sandbox traffic is measured but never capped

An explicit opt-in header meters the call to a separate sandbox period. Exploration stays visible without consuming or being blocked by the production allotment.

Ordering is deliberate

The gate runs after the context and burst limiter and before the route’s tenant database transaction opens, so a quota rejection never costs a transaction.

It is honest-off

Enforcement requires a provisioned database. Without one the store resolves to a no-database outcome and the gate is skipped entirely — not partially, not in a degraded mode. Nothing is counted and nothing is refused on quota grounds.

What the hash chain actually proves

Each increment folds the previous hash, the counter’s identity and the new running total into a fresh digest. The recorded head therefore commits to the entire increment sequence, so a counter that is silently rolled back to a lower value cannot reproduce its own chain head without replaying every step.

That is a real property and it is a narrow one, so here is the boundary stated plainly rather than left for you to discover. It is an append-linked integrity signal over one number’s history. It is not an independent event log: it does not record which routes were called, by whom, or when. It does not prove a call happened — only that the count was not quietly rewritten. And it is tamper-evident, not tamper-proof: an actor who can rewrite the counter and replay the chain from genesis defeats it. We describe it this narrowly on purpose, because “tamper-proof audit log” is exactly the phrase this mechanism does not earn.

The board

Built, built but not switched on, and not built

Three states, named separately, because collapsing the middle one into either neighbour is how a page becomes a lie. “Built but not switched on” means the code exists, is tested and is correct, and something outside it — a database, a decision, a vetting pass — is what stands between it and effect.

Questions

The ones an integrator actually asks

Honesty

What this page is careful about

Every capability described here was read out of a source file before it was written down, and the claims are deliberately bounded in four places where a looser sentence would have been easy to write. Metering enforces only where a database is provisioned. The integrity chain is tamper-evident over a counter, not an audit log. The public API is two routes, not a platform. And there are no client libraries at all.

There are no customer counts on this page, no adoption percentages, no benchmark figures and no named references, because none of those would be real. There is no pricing and no checkout. If something here later stops being true, the correction belongs on the page and not in a footnote.