anonymous plugin

21 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 enables auth without PII

The Anonymous plugin allows users to have an authenticated experience without requiring them to provide an email address, password, OAuth provider, or any other Personally Identifiable Information (PII). Users can later link an authentication method to their account when ready.

Import anonymous plugin from better-auth/plugins

To enable anonymous authentication, import the anonymous plugin from 'better-auth/plugins' and add it to the plugins array in the betterAuth configuration.

Anonymous plugin installation code example

Example of enabling the anonymous plugin in auth configuration: ```ts import { betterAuth } from "better-auth" import { anonymous } from "better-auth/plugins" export const auth = betterAuth({ plugins: [ anonymous() ] }) ```

Add anonymousClient to auth client

Include the anonymous client plugin in the authentication client instance by importing anonymousClient from 'better-auth/client/plugins' and adding it to the plugins array.

Anonymous client plugin installation code example

Example of enabling the anonymous client plugin: ```ts import { createAuthClient } from "better-auth/client" import { anonymousClient } from "better-auth/client/plugins" export const authClient = createAuthClient({ plugins: [ anonymousClient() ] }) ```

POST /sign-in/anonymous endpoint

The /sign-in/anonymous endpoint accepts a POST request with no required parameters and creates a new anonymous user with a generated email and configured or default name, then establishes a session.

signIn.anonymous() prevents duplicate anonymous sessions

If the current session belongs to an anonymous user, calling signIn.anonymous() again returns an error to prevent creating another anonymous user. The user 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 a user is signed in anonymously and tries to signIn or signUp with another method, their anonymous activities can be linked to the new account by providing an onLinkAccount callback to the plugin.

onLinkAccount callback receives anonymousUser and newUser

The onLinkAccount callback is called when an anonymous user links their account to a new authentication method. It receives an object with the anonymousUser and the newUser, allowing you to perform actions like moving cart items or other data from the anonymous user to the new user.

onLinkAccount callback configuration example

Example of configuring the onLinkAccount callback: ```ts 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 user deleted by default when linking account

By default, the anonymous user record is automatically deleted when the account is linked to a new authentication method.

POST /delete-anonymous-user endpoint

The /delete-anonymous-user endpoint accepts a POST request with no required parameters and deletes an anonymous user.

disableDeleteAnonymousUser prevents anonymous user deletion

Setting disableDeleteAnonymousUser to true will prevent the anonymous user from being able to call the /delete-anonymous-user endpoint and will disable the automatic deletion of the anonymous user when linking accounts.

emailDomainName option for anonymous email generation

The emailDomainName option sets the domain name to use when generating an email address for anonymous users. If not provided, the default format {id}@anonymous.placeholder.invalid is used. When emailDomainName is set, the format becomes temp-{id}@{domain}.

emailDomainName configuration example

Example of configuring emailDomainName: ```ts import { betterAuth } from "better-auth" import { anonymous } from "better-auth/plugins" export const auth = betterAuth({ plugins: [ anonymous({ emailDomainName: "example.com" // -> temp-{id}@example.com }) ] }) ```

generateRandomEmail custom function option

The generateRandomEmail option allows you to define a custom function to generate email addresses for anonymous users. This allows you to define your own email format. The function can be synchronous or asynchronous. You are responsible for ensuring the email is unique to avoid conflicts, and the returned email must be in a valid format.

generateRandomEmail configuration example

Example of configuring generateRandomEmail: ```ts 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` } }) ] }) ```

generateRandomEmail takes precedence over emailDomainName

If generateRandomEmail is provided, emailDomainName is ignored.

generateName callback 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 name is unique in your database.

Anonymous plugin schema requires isAnonymous field

The anonymous plugin requires an additional field in the user table named isAnonymous with type boolean (optional). This field indicates whether the user is anonymous.

How to link an anonymous user to a new authentication method

To link an anonymous user to a new authentication method, call signIn or signUp with the new authentication method (e.g., signIn.email). If an onLinkAccount callback is configured in the anonymous plugin options, it will be called with the anonymousUser and newUser objects, allowing you to migrate data from the anonymous account. The anonymous user record is then deleted by default unless disableDeleteAnonymousUser is set to true.

Give your agent this brain