Skip to main content
One-time tokens are short-lived, single-use strings for flows like email verification, password resets, and invitations. The raw token is handed to the caller once and never stored, only a SHA-256 hash lives in the database. On first use (or expiry), the token is gone.

Setup

The module is part of theAuth core. No extra plugin needed.
lib/theauth.ts
theauth.oneTimeTokens is always available and uses the default config (one hour TTL). To change the default TTL, create your own instance with createOneTimeTokenModule:

Token purposes

Each token has a purpose that scopes its validity. Validation fails if the purpose at creation does not match the purpose at consumption.

Creating a token

createToken returns the raw token exactly once. Put it in a link or hand it to your mailer, there is no way to recover it from the database later.
The default TTL is 3600 seconds (1 hour). Override it per call with ttlSeconds, or set defaultTtlSeconds on a module you create with createOneTimeTokenModule to change the default for all tokens. The raw token is 64 hex characters (32 random bytes).

Validating a token

Call validateToken when the user lands on your reset or verification page. On success, the token is consumed immediately, a second call with the same token always fails.
validateToken marks the token as used before it returns. Even if your handler crashes after this call, the token cannot be reused. Handle the downstream action (password update, email confirmation) in the same request.

Revoking tokens

Revoke all active tokens for an identifier when a user takes an action that makes them obsolete, for example, invalidating outstanding reset links when a user changes their password through a different flow.
Revocation is a soft operation, tokens are marked as used, not deleted. Only active (unused, unexpired) tokens are counted. The purpose argument must be one of the four purpose values.

Attaching metadata

Pass a metadata object to store arbitrary data alongside the token. It is returned on successful validation.

Error codes

Security notes

Tokens are hashed at rest. Only a SHA-256 hash is stored. A database dump does not expose usable tokens. Single-use marking. The module reads the token, then marks it used with a conditional WHERE used = false update before returning. It does not check how many rows the update changed, so two truly simultaneous requests with the same token could both succeed. If that matters for your flow, make the downstream action idempotent. A purpose mismatch returns TOKEN_PURPOSE_MISMATCH without consuming the token. Purpose binding prevents cross-flow reuse. A password-reset token cannot be submitted to an email-verify endpoint.

Sessions

Cookie and JWT sessions you can issue after a token validates.

Email templates

Email templates for reset and verification messages.

Hooks

Lifecycle hooks you can attach to your instance.

Error codes

theAuth error codes with their HTTP status and meaning.
Last modified on October 7, 2026