The problem
A browser cannot hold a long-lived signing key. Shipping one to a page is shipping it to every extension, every debugger, and every copy of that page’s storage.
The answer
The management client’s server mints a short-lived, single-scope, user-bound token and hands it to the browser, which then calls your Worker directly.
Response bodies never touch their origin on that path, and their private key never leaves their server.
Your own console goes in allowedOrigins. Each entry is a scheme and a host — https://ops.example.com, http://localhost:5173, http://[::1]:5173. A trailing slash or an explicit :443 is the same origin spelled differently and is accepted; a path, a query or a credential is refused when the config is parsed, at deploy, because those look like they scope the entry and they do not.
controlplane({ allowedOrigins: ["https://ops.example.com"] })In local dev you configure nothing: when ENVIRONMENT is dev, your Worker answers for any address on your own machine, on any port. The dev port allocator picks a console’s port per feature, so there is no value you could write into allowedOrigins that would stay true across checkouts. It is dev and loopback or it is nothing — in staging and production the allow-list is the config and nothing else.
It grants no access. Every admin route still demands a verified control-plane token, so what this permits a local page to do is read a reply it could already provoke. Two properties are deliberate: the list is read from config and never from a connection row, because a preflight is answered before any credential is read and consulting the database would turn it into a way for anyone to ask which origins you have registered; and an origin that is not on the list gets the same 204 and the same empty body as one that is, minus the header that permits the read. Your browser console will name it as a CORS failure; your Worker will not tell you more than that, on purpose.
A browser caches a preflight for corsMaxAgeSeconds, ten minutes by default. Set it to 0 while you are working an allow-list out: a browser that has cached a refusal keeps refusing for the whole window after you fix the config, which reads exactly like a change that did not take. Cookies are never in play — the token is a header, so Access-Control-Allow-Credentials is never sent.
Your Worker cannot tell the difference, deliberately
A browser call and a machine call are the same 60-second, single-scope, body-bound token, verified by the same code.
There is no second token class to get wrong, and no route whose auth model depends on which client made the call.
What does transit their infrastructure
The calls a management client makes from its own server, which for the hosted dashboard are two: the ping that proves a new connection answers, and the key rotation that appends a successor. Both have to be server-side, because only a server holds a private key — and neither carries a pane’s data.
For anything that does reach their origin, the commitment is a zero-logging policy on your data: response bodies fetched from your Worker are not logged, cached, or persisted.
What is stored is theirs — users, subscriptions, connection metadata, and their own private keys. Never your users, your purchases, your audit events, or your support mail.
Eleven things a call must satisfy
Every step default-denies.
- Read the key id from the token header and the audience from its claims. Untrusted at this point — a parsed token is a well-formed shape, never an authentic one.
- Load the connection the audience names. None registered:
controlplane/not_connected. - The key must exist on that connection, not be revoked, and be inside its validity window.
- Verify the signature via WebCrypto. The algorithm is pinned to the literal
EdDSAat parse — the algorithm-confusion defense. - The audience must equal the loaded connection’s id, and its environment must equal this Worker’s. A staging credential cannot reach production.
- The issuer must equal the one that connection was registered against.
- Expiry and issued-at are checked with a bounded clock skew, and a token claiming a lifetime longer than the configured maximum is rejected outright.
- The SHA-256 digest of the raw body is recomputed and compared. A signature over claims that did not bind the body would let an attacker swap the payload.
- The scope check. A refusal here is
controlplane/insufficient_scope, and it spends the token id too, so a token refused for scope cannot be presented again at a route it does cover. Only its first presentation names the caller on the audit row. - The token id is claimed in the replay set, as a single-use insert. Last, because it is the only step that writes anything a granted call depends on.
- An audit event is emitted — allowed or denied — and only then does the handler run.
The replay guard is a guarantee, not a best effort
The claim is a single-use insert where the token id is the primary key — insert, on conflict do nothing, returning. The insert either wins the key or conflicts, so there is no window between deciding and recording, and of any number of concurrent presentations SQLite admits exactly one, wherever those requests landed.
It is the same move auth makes on the other side, consuming a refresh token with a conditional delete.
The key is the token id alone, not the pair of token and connection. A composite would let a token captured from one connection be spent again against another — which is the property the guard exists to deny. The connection id is recorded beside it for the incident, never for the decision.
The cost of closing it is one database write, and here that is close to free. A control-plane hot path is an administrator clicking something — low volume, high privilege — which is a different calculation from a per-request user path.
Rows carry an expiry and are pruned after a successful claim, so the table cannot only grow. Pruning deliberately does not run on a refused claim — otherwise replaying one token in a loop would drive an unbounded delete per attempt.
The KV backend is still selectable behind the same interface. It remains best-effort, with the race above as its stated price, and is a reasonable trade only where every management operation is idempotent. Choosing it also brings back the KV binding; the default needs no KV namespace at all.
Nothing is left behind
A control-plane call creates nothing in Better Auth. That is precisely why this is its own strategy rather than a flavor of bearer.
A dashboard user is not a user of your app. Minting a user or session row for one would put people who never signed up into your user table — inflating your counts, appearing in your data-subject exports, and creating a credential that might reach routes it was never scoped for.
The verified caller lands on c.var.controlPlane, never on c.var.auth. If it landed on auth, every requireAuth() in every capability would pass for a management client — a scope escalation across the whole tree from one convenient assignment. A test asserts the isolation, because it is the kind of property that regresses silently.
Exactly two things outlive a call: the token id in the replay set, and the audit event. Both tables are in the reference.