Skip to main content
The 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
The plugin throws at startup unless 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)
The response is { 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)
The body takes 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.
Deleting anonymous users is permanent. Any app data tied to their user ID will become orphaned unless you cascade deletes in your schema.

Configuration reference

number
default:"86400 (24 hours)"
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).
boolean
default:"false"
Whether anonymous users may create agents. Accepted in the config type but not enforced by the plugin endpoints.

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.
Last modified on October 7, 2026