Auth

Authenticates a user by email and password. The response has two terminal shapes:

• 201 Created when 2FA is OFF — the regular {access_token, refresh_token, user} payload.
• 200 OK when 2FA is ON — a challenge_token to spend on POST /auth/2fa/verify within 5 minutes. No tokens are issued yet.

A 401 invalid email or password is returned for both "wrong password" and "email not registered" — same wording either way, to prevent account enumeration.

The access JWT has a 1-hour TTL and is signed with a secret separate from the dashboard's, so a leak on one surface does not compromise the other. The refresh token (cmrr_...) has a 30-day TTL and is rotated on every successful /auth/refresh call.

Completes a 2FA login by spending the challenge_token returned by /auth/login plus a TOTP or recovery code. Server tries TOTP first then falls back to recovery codes — the client does not need to specify which one it is sending.

Recovery codes are single-use and hashed at rest. The challenge_token is also single-use (~5 minute TTL); a replayed token returns 401.

Trades a refresh token for a fresh access + refresh pair. Rotation is enforced — the spent refresh row is revoked, and the response carries a NEW refresh token. The client MUST replace its stored value with the new one; replaying the previous refresh returns 401.

A leaked refresh token can therefore only be exploited once.

Revokes a refresh row. The access token itself is not invalidated (JWTs are stateless), but it expires in ~1 hour and the client should drop its local copy on logout.

Idempotent: revoking a row that is already revoked returns 200 with revoked: 0.

With all_devices: true this becomes the Sign out everywhere button — every active refresh row for the user is revoked. The refresh_token field is still required as proof-of-possession even when all_devices is set.