anonymousAuth plugin creates a lightweight guest identity on demand. The guest gets a real session and can use your app. When they decide to register, the guest user is upgraded in place by setting an email, so the user ID and any data tied to it are unchanged.
Anonymous users are rows in the users table with a placeholder email (anon_<id>@theauth.anonymous) and a { anonymous: true } metadata flag.
Setup
lib/theauth.ts
auth.session is configured. Its config is optional, anonymousAuth() works with defaults.
Create guest
POST /auth/anonymous
Creates a new anonymous user and returns a session token. No request body needed.
Create guest (client)
{ userId, sessionToken }. The plugin does not set a cookie, so your app stores the token. The endpoint is rate limited per IP address (20 requests per window).
Check status
GET /auth/anonymous/status
Requires an authenticated request. Returns { anonymous: boolean }, which is true while the user is an un-upgraded guest.
Upgrade to real account
POST /auth/anonymous/upgrade
Requires an authenticated anonymous session. Sets the real email (and optionally a name) on the guest user. The session stays valid and the user ID does not change.
Upgrade guest (client)
email (required) and name. It does not take a password, so after upgrading you attach a sign-in method (for example magic link or email OTP) to that email. The endpoint does not check whether the email is already used by another account, and users have a unique email constraint, so a duplicate email fails with a 500 error.
Error responses
Guest cleanup
Anonymous accounts that are never upgraded accumulate. The plugin does not schedule cleanup and does not expose the cleanup function. Use the module directly, with the instance’s database and session manager:Scheduled cleanup
cleanup(maxAgeMs) deletes anonymous users created before the cutoff (default 24 hours) along with their sessions, and returns the number of users removed. It selects on creation time, not last activity.
Configuration reference
Intended lifetime of anonymous sessions, in seconds. Currently this value is only recorded in the session metadata. The session itself expires after
auth.session.maxAge (7 days by default).Whether anonymous users may create agents. Accepted in the config type but not enforced by the plugin endpoints.
Related
Email and password
Full registration flow users can upgrade into from a guest session.
Magic link
Passwordless sign-in that anonymous users can upgrade into.
Sessions
How theAuth manages session lifetime and cookie settings.
Hooks
Lifecycle hooks you can attach to your instance.