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 apurpose 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.
- password reset
- email verify
- invitation
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
CallvalidateToken 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.
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.purpose argument must be one of the four purpose values.
Attaching metadata
Pass ametadata 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 conditionalWHERE 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.
Related
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.