# Accounts and keys

An account is a tenant. Every credential resolves to exactly one, and the
account is taken from the credential and never from the request — which is what
makes cross-tenant access impossible rather than merely discouraged. There is no
field a caller could set to reach another account's data, because there is no
field.

## Two kinds of credential

|  | Integration key | Operator key |
| --- | --- | --- |
| Looks like | `acr_live_…` | `acr_admin_…` |
| Belongs to | One account | Nobody — it is global |
| Scopes | `read`, `write` | `read`, `write`, `money` |
| Used by | A client's server | An operator, usually over MCP |
| Reaches | `/v1/*` | `/admin/*`, `/stats/*` |

Both are stored as a SHA-256 hash and nothing else, so a leaked database does
not hand over working credentials. Both are shown exactly once, in the response
to the call that created them; if one is lost the answer is a new key, not a
recovery.

Both are compared in constant time even though they are looked up by hash, so a
timing difference cannot distinguish "revoked" from "no such key".

## Scopes

Scopes nest: `write` implies `read`, and `money` implies both. A key that lacks
the scope for a route is refused with **403, not 401** — the credential is
valid, it simply may not do this, and telling the two apart is what lets a
caller fix the right thing.

`money` is never issued to a tenant. It exists for the operator identity and
gates the two calls that create or destroy an operator: minting an admin key,
and revoking one.

Issue the narrowest scope that does the job. A partner service that only draws
a leaderboard has no business holding a key that can enrol.

## Retiring the shared token

A single `ADMIN_TOKEN` environment variable once guarded every operator route,
with no actor behind any action. That was the disqualifying finding of the
access-control audit: an append-only record of who did what is impossible when
every action is taken by the same anonymous secret.

Operator keys replace it. The old token still works as a full-scope bridge so
nothing breaks mid-migration, and it records its actions against the stand-in
actor `legacy-admin-token`. Entries with that actor are the remaining work: each
one is a consumer that has not moved to a key of its own.

**One key per person.** A key shared between two operators makes the audit trail
a lie in a way that is worse than having no audit trail, because it looks like
one.

## The audit log

Every successful non-GET on an operator or partner route writes one row: the
actor, what kind of actor it was, the method and path, and the account it
touched.

Reads are not recorded — a read is not an action — and failures are not
recorded, because nothing changed. Writing the audit row is best-effort: an
outage of that table must never fail the operation it is recording, so it is
wrapped and swallowed. Every privileged mutation should still call it.

Read it with `GET /admin/audit`, optionally filtered to one `actor`.

## Rate limits

Integration keys are limited to **600 requests per minute per key**, counted in
Postgres as one row per key per minute.

It is counted in the database rather than in memory because the API runs as
serverless functions: an in-process counter is per-instance and resets on every
cold start, which is to say it is not a limit.

Responses carry `x-ratelimit-limit` and `x-ratelimit-remaining`. A 429 carries
`retry-after` in seconds, exact rather than estimated because the window is
wall-clock aligned.

**The limiter fails open.** If its own table is unavailable, requests pass. A
partner's creator dashboard calls enrolment on every load, and a limiter that
can take that down when it has its own outage is worse than no limiter. The
failure it defends against is a runaway loop on a client's side, not a
determined attacker holding a valid account credential.

Override with `V1_RATE_LIMIT_PER_MINUTE` on the track deployment.

## Test mode

Keys carry a `livemode` flag, and **nothing is isolated behind it yet.** A test
key would write to the same campaigns, creators and clicks as a live one.

Test keys are therefore not issued. Offering one that implies isolation it does
not have would be worse than not offering one at all. A partner integrating
should build against a campaign of their own, pointed at a URL they control.
