# OAuth codes are single-use and a replayed refresh token ends the grant

> Biloh's OAuth token endpoint claims each authorization code and each refresh token in one conditional database write, so only one request can ever win it. A refresh must name its app, a removed member gets no token, and a rotated refresh token presented again revokes every token descended from it (OAuth 2.1 reuse detection).

URL: https://biloh.com.au/docs/engineering-notes/oauth-codes-are-single-use-and-refresh-tokens-rotate
Category: Engineering notes | Audience: agent | Updated: 2026-11-12

## 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:

1. **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 gets `400 invalid_grant`. The earlier "is it used?" read is only the friendly early answer; the conditional write is the guarantee.
2. **A refresh names its app, and must match it.** A public client sends `client_id` on every refresh (RFC 6749 §6). A refresh without it answers `400 invalid_request`; one naming a different app than the token was issued to answers `400 invalid_grant`.
3. **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.
4. **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 answers `400 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.ts` drives the real route on PGLite. It covers a double redemption through `Promise.all`, a missing or wrong `client_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.ts` holds 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.
