anonymous authentication

11 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Anonymous plugin installation and setup

The Anonymous plugin allows users to have an authenticated experience without providing email, password, OAuth provider, or any PII. To enable it, import the anonymous plugin from 'better-auth/plugins' and add it to the plugins array in the betterAuth config. Then run npx auth migrate or npx auth generate to update the database schema. Finally, add the anonymousClient plugin to your client instance by importing it from 'better-auth/client/plugins'.

Sign in anonymously endpoint

The signIn.anonymous() method creates a new user with a generated email and configured or default name, then establishes a session. The endpoint is POST /sign-in/anonymous with an empty request body (type signInAnonymous = {}). If the current session belongs to an anonymous user, calling signIn.anonymous() again returns an error. You must link the current account using another authentication method or sign out before starting a new anonymous session.

Link anonymous account to new authentication method

When an anonymous user calls signIn or signUp with another authentication method, their anonymous activities can be linked to the new account. To enable this, provide an onLinkAccount callback to the anonymous plugin that receives an object with anonymousUser and newUser properties. By default, the anonymous user record is automatically deleted when the account is linked. Call signIn or signUp with another method (e.g., authClient.signIn.email()) to trigger the linking process.

Delete anonymous user endpoint

The /delete-anonymous-user endpoint is a POST request with an empty body (type deleteAnonymousUser = {}). It allows deletion of an anonymous user. By default, the anonymous user is deleted automatically when the account is linked to a new authentication method. Setting disableDeleteAnonymousUser to true prevents the anonymous user from calling this endpoint.

Anonymous plugin emailDomainName option

The emailDomainName option specifies the domain name to use when generating an email address for anonymous users. If not provided, the default format is {id}@anonymous.placeholder.invalid. When emailDomainName is set (e.g., to 'example.com'), the generated email format becomes temp-{id}@example.com.

Anonymous plugin generateRandomEmail option

The generateRandomEmail option accepts a custom function (synchronous or asynchronous) to generate email addresses for anonymous users, allowing you to define your own email format. If generateRandomEmail is provided, the emailDomainName option is ignored. You are responsible for ensuring the generated email is unique to avoid conflicts, and the returned email must be in a valid format.

Anonymous plugin onLinkAccount callback

The onLinkAccount option is a callback function called when an anonymous user links their account to a new authentication method. The callback receives an object containing anonymousUser and newUser properties, allowing you to perform actions such as migrating data (like moving cart items) from the anonymous user to the new user.

Anonymous plugin disableDeleteAnonymousUser option

The disableDeleteAnonymousUser option is a boolean that defaults to false. By default, when an anonymous user links their account to a new authentication method, the anonymous user record is automatically deleted. Setting disableDeleteAnonymousUser to true disables this automatic deletion and makes the /delete-anonymous-user endpoint inaccessible to anonymous users.

Anonymous plugin generateName option

The generateName option is a callback function that is called to generate a name for the anonymous user. It is useful if you want to have random names for anonymous users or if the name field is unique in your database.

Anonymous authentication example with onLinkAccount callback

import { betterAuth } from "better-auth" import { anonymous } from "better-auth/plugins" export const auth = betterAuth({ plugins: [ anonymous({ onLinkAccount: async ({ anonymousUser, newUser }) => { // perform actions like moving the cart items from anonymous user to the new user } }) ] })

Anonymous authentication example with custom email generation

import { betterAuth } from "better-auth" import { anonymous } from "better-auth/plugins" export const auth = betterAuth({ plugins: [ anonymous({ generateRandomEmail: () => { const id = crypto.randomUUID() return `guest-${id}@example.com` } }) ] })

Give your agent this brain