Skip to main content
The phone module registers and authenticates users with a phone number and a one-time code. You supply the SMS delivery function. theAuth generates the code, hashes it before storage, enforces expiry, and limits verification attempts. It ships as a config key, not a plugin: there is no phoneAuth() plugin export.

Setup

lib/theauth.ts
theauth.phone is null unless the phone key is passed and auth.session is configured (a session is issued on verification). Forward matching requests to it from a catch-all route:
Mount the handler
handleRequest handles POST only and matches the literal pathnames below. If you mount it under a prefix such as /api/theauth, strip the prefix from the URL first. See adapters.

Send code

POST /auth/phone/send-code Sends a one-time code to the given phone number, replacing any earlier code for that number.
Send code (client)
Use E.164 format (+ prefix, country code, number). theAuth only strips whitespace and does not validate or reformat the number, so normalize it before you call. A missing phoneNumber returns 400. The module has no built-in rate limit for sending, so add one in front of this route (see rate limiting) to limit SMS cost and abuse.

Verify code

POST /auth/phone/verify Submits the code the user received. Returns the user and a session token on success. The user account is created on the first successful verification.
Verify code (client)
Responses The handler does not set a cookie, so your app stores the session token.

Configuration reference

(phoneNumber: string, code: string) => Promise<void>
required
Callback invoked to deliver the code. Receives the phone number and the numeric code as a string.
number
default:6
Number of digits in the generated code.
number
default:"300 (5 min)"
Code validity window in seconds.
number
default:5
Verification attempts allowed per code before it stops being accepted.

Email OTP

OTP via email instead of SMS.

Magic link

Passwordless sign-in via email link.

Passkey

Device biometric auth as a phone-free alternative.

Authentication overview

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