Skip to main content
Email OTP sends a short numeric code to the user’s inbox. It works well for mobile flows where clicking a link is awkward and for verification steps inside an existing session.

Setup

1

Install

2

Add the plugin

lib/theauth.ts
The plugin throws at startup unless auth.session is configured, because it issues a session on successful verification. auth.session.secret must be at least 32 characters.You can also pass the same options as a top-level emailOtp key to createTheAuth instead of using the plugin. That exposes theauth.emailOtp (sendCode, verifyCode, handleRequest), which is null when the key is absent or auth.session is not set.

How it works

  1. User submits their email to POST /auth/email-otp/send.
  2. theAuth generates a cryptographically random code and calls your sendOtp function with the email and code.
  3. User enters the code in your UI and submits to POST /auth/email-otp/verify.
  4. On success, the response contains the user and a session token. theAuth does not set a cookie, so your app stores the token.
If the email belongs to an existing account, the same user ID is returned. If it is new, an account is created on successful verification.

Send a code

POST /auth/email-otp/send
A successful response is 200 with { "sent": true }. The email is trimmed and lowercased, and a missing email returns 400. Requesting a new code deletes any earlier code for that address. The endpoint is limited to 5 requests per minute per IP address, and requests over the limit return 429. Build a countdown timer into your UI.

Verify a code

POST /auth/email-otp/verify
A wrong, expired, or exhausted code returns 401. After maxAttempts verification attempts the stored code stops being accepted and a new one must be requested. Verification is limited to 10 requests per minute per IP address.
Codes are single-use. A successful verification invalidates the code immediately. Do not retry the same code after a success response.

Options

Redeeming a link or code marks the address verified. The cleanup stops account pre-hijacking: someone who registered the victim’s address first would otherwise keep the password they set after the victim signs in.

Magic link

Single-use email link as an alternative to numeric codes.

Phone number

OTP delivered via SMS instead of email.

Email and password

Password-based auth that can run alongside OTP.

Authentication overview

All sign-in methods available in theAuth.
Last modified on October 19, 2026