What does the token endpoint guarantee?
POST /api/oauth/token is where an AI assistant exchanges a sign-in code for tokens, and later renews them. Four guarantees hold on it:
- A code is redeemed once, even under a race. The code is consumed in one conditional write,
UPDATE … SET used_at = now() WHERE code = $1 AND used_at IS NULL RETURNING. Two requests carrying the same code and verifier at the same instant cannot both succeed: one gets tokens, the other gets400 invalid_grant. The earlier "is it used?" read is only the friendly early answer; the conditional write is the guarantee. - A refresh names its app, and must match it. A public client sends
client_idon every refresh (RFC 6749 §6). A refresh without it answers400 invalid_request; one naming a different app than the token was issued to answers400 invalid_grant. - Only a live member gets a token. The persona is resolved from an active, undeleted membership (or a live platform-admin row) at the moment of issue and at every renewal. If there is none, or the read fails, the answer is
400 invalid_grant. Issuing a token fails closed. - A replayed refresh token ends the grant. Rotation claims the old token in one conditional write,
WHERE token_hash = $1 AND revoked_at IS NULL, stores the new one, and only then signs the access token. If a refresh token that was already rotated is presented again, or a concurrent request loses the claim, the endpoint revokes every refresh token of that grant issued at or after it, and answers400 invalid_grant(OAuth 2.1 §4.3.1 reuse detection). A stolen token and the real one cannot both live on.
Which address does a token belong to?
The address the assistant signed in at. Every token is bound to the MCP endpoint of the host the request reached (its audience), for both grants. An RFC 8707 resource that names any other address is refused 400 invalid_target. Businesses connect at one shared address, https://connect.biloh.com.au/api/mcp/mcp. A token issued there is always a business token, never a platform one, and while that address is switched off in settings its token endpoint answers 400 invalid_grant.
Can someone guess codes by hammering the endpoint?
No. The endpoint accepts 30 token requests a minute from one IP address and answers 429 slow_down past that. If the rate limiter cannot be reached, the endpoint answers 503 rather than letting requests through unchecked.
What if a write fails half way?
Every write's error is checked. If the old token cannot be claimed, the answer is 503 and the old token stays usable once. If the new token cannot be stored, the claim on the old one is undone, so a storage blip does not sign the connection out, and the answer contains no token.
Do personal access tokens follow the same rules?
Platform-scoped personal access tokens work only while their owner holds a live platform-admin row. A removed admin's key is refused 401 membership_revoked on its next call. New platform keys get the same default expiry and the same per-person cap as tenant keys, from the one policy home, lib/auth/pat-policy.ts.
How is it locked?
tests/api/oauth/security-review-73f04315-token.test.tsdrives the real route on PGLite. It covers a double redemption throughPromise.all, a missing or wrongclient_id, a member removed between code and redemption, a replayed rotated token revoking its family, and a failed revoke or insert.security-review-6486fef6-platform-pat.test.ts(in the MCP API tests) covers a removed platform admin, the default expiry and the cap.tests/structural/wp-oauth-harden-locks.test.tsholds both key-minting tools to the one policy home.
What should an assistant do with these answers?
Treat invalid_grant on a refresh as "sign in again". Send client_id on every refresh, and send each refresh token once: a client that fires two renewals with the same token at the same instant will have its grant revoked by design, and has to reconnect.