POST
Verify email (OTP)

Overview

Verifies the 6-digit OTP that was sent to the user’s email during registration (or via POST /resend-verify-email). On success:
  1. The OTP row is marked consumed.
  2. users.emailVerified is set to true.
  3. A new session is minted — access token (RS256 JWT, 15-min TTL) + refresh token (256-bit opaque, 30-day TTL, single-use rotating).
Wrong codes increment attemptsUsed and return 401 INVALID_CODE. After 5 attempts the row is dead and further calls return 401 CODE_EXPIRED; the client must request a fresh code. A valid, live code is always required, including for an account that is already verified: this endpoint takes no password, so the code is the only proof of ownership. A repeated call with a consumed code returns CODE_EXPIRED; the client should send the user to /auth/login instead.

Authentication

None required — this endpoint is part of the login sequence.

Path parameters

None.

Query parameters

None.

Request body

Example payload

Response — 200 OK

User object

Example response

Error responses

Example error — 401 INVALID_CODE

Side effects

  • Marks the OTP row consumed (consumedAt = now).
  • Sets users.emailVerified = true.
  • Inserts a refresh_tokens row keyed by the new session id.

See also

curl