Better Auth — Best Practices for Common Features

This skill combines the three highest-traffic Better Auth feature areas. Pick the section that matches what you're implementing — the parent

better-auth

skill has the integration story;

better-auth-security

covers cross-cutting hardening; this one covers feature-by-feature best practices.

Feature	Section
Email + password (verification, reset, hashing, policies)	Email/Password
Organizations, teams, RBAC	Organization plugin
Two-factor authentication (TOTP, backup codes, recovery)	Two-Factor (2FA)

For Tauri-specific integration, see

better-auth-tauri-setup

. For OAuth/social providers, see

better-auth-providers

. For the broader integration overview, see

better-auth

Email/Password

Quick Start

Enable email/password:
```
emailAndPassword: { enabled: true }
```
Configure
```
emailVerification.sendVerificationEmail
```
Add
```
sendResetPassword
```
for password reset flows
Run
```
npx @better-auth/cli@latest migrate
```
Verify: attempt sign-up and confirm verification email triggers

Email Verification Setup

Configure

emailVerification.sendVerificationEmail

to verify user email addresses.

Requiring Email Verification

For stricter security, enable

emailAndPassword.requireEmailVerification

to block sign-in until the user verifies their email.

Client Side Validation

Implement client-side validation for immediate user feedback and reduced server load.

Callback URLs

Always use absolute URLs (including the origin) for callback URLs in sign-up and sign-in requests.

Password Reset Flows

Provide

sendResetPassword

in the email and password config to enable password resets.

Security Considerations

Built-in protections: background email sending (timing attack prevention), dummy operations on invalid requests, constant response messages regardless of user existence.

On serverless platforms, configure a background task handler using

waitUntil

Token Security

Tokens expire after 1 hour by default. Configure with

resetPasswordTokenExpiresIn

(in seconds). Tokens are single-use.

Session Revocation

Enable

revokeSessionsOnPasswordReset

to invalidate all existing sessions on password reset.

Password Requirements

Password length limits configurable via

minPasswordLength

and

maxPasswordLength

Password Hashing

Default:

scrypt

(Node.js native, no external dependencies).

Custom Hashing Algorithm

To use Argon2id or another algorithm, provide custom

hash

and

verify

functions.

Note: If you switch hashing algorithms on an existing system, users with passwords hashed using the old algorithm won't be able to sign in. Plan a migration strategy if needed.

Organization plugin

Setting Up Organizations

When adding organizations to your application, configure the

organization

plugin with appropriate limits and permissions.

import { betterAuth } from "better-auth";
import { organization } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    organization({
      allowUserToCreateOrganization: true,
      organizationLimit: 5, // Max orgs per user
      membershipLimit: 100, // Max members per org
    }),
  ],
});

Note: After adding the plugin, run

npx @better-auth/cli migrate

to add the required database tables.

Client-Side Setup

Add the client plugin to access organization methods:

import { createAuthClient } from "better-auth/client";
import { organizationClient } from "better-auth/client/plugins";

export const authClient = createAuthClient({
  plugins: [organizationClient()],
});

Creating Organizations

Organizations are the top-level entity for grouping users. When created, the creator is automatically assigned the

owner

role.

const createOrg = async () => {
  const { data, error } = await authClient.organization.create({
    name: "My Company",
    slug: "my-company",
    logo: "https://example.com/logo.png",
    metadata: { plan: "pro" },
  });
};

Controlling Organization Creation

Restrict who can create organizations based on user attributes:

organization({
  allowUserToCreateOrganization: async (user) => {
    return user.emailVerified === true;
  },
  organizationLimit: async (user) => {
    // Premium users get more organizations
    return user.plan === "premium" ? 20 : 3;
  },
});

Creating Organizations on Behalf of Users

Administrators can create organizations for other users (server-side only):

await auth.api.createOrganization({
  body: {
    name: "Client Organization",
    slug: "client-org",
    userId: "user-id-who-will-be-owner", // `userId` is required
  },
});

Note: The

userId

parameter cannot be used alongside session headers.

Active Organizations

The active organization is stored in the session and scopes subsequent API calls. Always set an active organization after the user selects one.

const setActive = async (organizationId: string) => {
  const { data, error } = await authClient.organization.setActive({
    organizationId,
  });
};

Many endpoints use the active organization when

organizationId

is not provided:

// These use the active organization automatically
await authClient.organization.listMembers();
await authClient.organization.listInvitations();
await authClient.organization.inviteMember({ email: "user@example.com", role: "member" });

Getting Full Organization Data

Retrieve the active organization with all its members, invitations, and teams:

const { data } = await authClient.organization.getFullOrganization();
// data.organization, data.members, data.invitations, data.teams

Members

Members are users who belong to an organization. Each member has a role that determines their permissions.

Adding Members (Server-Side)

Add members directly without invitations (useful for admin operations):

await auth.api.addMember({
  body: {
    userId: "user-id",
    role: "member",
    organizationId: "org-id",
  },
});

Note: For client-side member additions, use the invitation system instead.

Assigning Multiple Roles

Members can have multiple roles for fine-grained permissions:

await auth.api.addMember({
  body: {
    userId: "user-id",
    role: ["admin", "moderator"],
    organizationId: "org-id",
  },
});

Removing Members

Remove members by ID or email:

await authClient.organization.removeMember({
  memberIdOrEmail: "user@example.com",
});

Important: The last owner cannot be removed. Assign the owner role to another member first.

Updating Member Roles

await authClient.organization.updateMemberRole({
  memberId: "member-id",
  role: "admin",
});

Membership Limits

Control the maximum number of members per organization:

organization({
  membershipLimit: async (user, organization) => {
    if (organization.metadata?.plan === "enterprise") {
      return 1000;
    }
    return 50;
  },
});

Invitations

The invitation system allows admins to invite users via email. Configure email sending to enable invitations.

Setting Up Invitation Emails

import { betterAuth } from "better-auth";
import { organization } from "better-auth/plugins";
import { sendEmail } from "./email";

export const auth = betterAuth({
  plugins: [
    organization({
      sendInvitationEmail: async (data) => {
        const { email, organization, inviter, invitation } = data;

        await sendEmail({
          to: email,
          subject: `Join ${organization.name}`,
          html: `
            <p>${inviter.user.name} invited you to join ${organization.name}</p>
            <a href="https://yourapp.com/accept-invite?id=${invitation.id}">
              Accept Invitation
            </a>
          `,
        });
      },
    }),
  ],
});

Sending Invitations

await authClient.organization.inviteMember({
  email: "newuser@example.com",
  role: "member",
});

Creating Shareable Invitation URLs

For sharing via Slack, SMS, or in-app notifications:

const { data } = await authClient.organization.getInvitationURL({
  email: "newuser@example.com",
  role: "member",
  callbackURL: "https://yourapp.com/dashboard",
});

// Share data.url via any channel

Note: This endpoint does not call

sendInvitationEmail

. Handle delivery yourself.

Accepting Invitations

await authClient.organization.acceptInvitation({
  invitationId: "invitation-id",
});

Invitation Configuration

organization({
  invitationExpiresIn: 60 * 60 * 24 * 7, // 7 days (default: 48 hours)
  invitationLimit: 100, // Max pending invitations per org
  cancelPendingInvitationsOnReInvite: true, // Cancel old invites when re-inviting
});

Roles & Permissions

The plugin provides role-based access control (RBAC) with three default roles:

Role	Description
`owner`	Full access, can delete organization
`admin`	Can manage members, invitations, settings
`member`	Basic access to organization resources

Checking Permissions

const { data } = await authClient.organization.hasPermission({
  permission: "member:write",
});

if (data?.hasPermission) {
  // User can manage members
}

Client-Side Permission Checks

For UI rendering without API calls:

const canManageMembers = authClient.organization.checkRolePermission({
  role: "admin",
  permissions: ["member:write"],
});

Note: For dynamic access control, the client side role permission check will not work. Please use the

hasPermission

endpoint.

Teams

Teams allow grouping members within an organization.

Enabling Teams

import { organization } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    organization({
        teams: {
            enabled: true
        }
    }),
  ],
});

Creating Teams

const { data } = await authClient.organization.createTeam({
  name: "Engineering",
});

Managing Team Members

// Add a member to a team (must be org member first)
await authClient.organization.addTeamMember({
  teamId: "team-id",
  userId: "user-id",
});

// Remove from team (stays in org)
await authClient.organization.removeTeamMember({
  teamId: "team-id",
  userId: "user-id",
});

Active Teams

Similar to active organizations, set an active team for the session:

await authClient.organization.setActiveTeam({
  teamId: "team-id",
});

Team Limits

organization({
  teams: {
      maximumTeams: 20, // Max teams per org
      maximumMembersPerTeam: 50, // Max members per team
      allowRemovingAllTeams: false, // Prevent removing last team
  }
});

Dynamic Access Control

For applications needing custom roles per organization at runtime, enable dynamic access control.

Enabling Dynamic Access Control

import { organization } from "better-auth/plugins";
import { dynamicAccessControl } from "@better-auth/organization/addons";

export const auth = betterAuth({
  plugins: [
    organization({
        dynamicAccessControl: {
            enabled: true
        }
    }),
  ],
});

Creating Custom Roles

await authClient.organization.createRole({
  role: "moderator",
  permission: {
    member: ["read"],
    invitation: ["read"],
  },
});

Updating and Deleting Roles

// Update role permissions
await authClient.organization.updateRole({
  roleId: "role-id",
  permission: {
    member: ["read", "write"],
  },
});

// Delete a custom role
await authClient.organization.deleteRole({
  roleId: "role-id",
});

Note: Pre-defined roles (owner, admin, member) cannot be deleted. Roles assigned to members cannot be deleted until members are reassigned.

Lifecycle Hooks

Execute custom logic at various points in the organization lifecycle:

organization({
  hooks: {
    organization: {
      beforeCreate: async ({ data, user }) => {
        // Validate or modify data before creation
        return {
          data: {
            ...data,
            metadata: { ...data.metadata, createdBy: user.id },
          },
        };
      },
      afterCreate: async ({ organization, member }) => {
        // Post-creation logic (e.g., send welcome email, create default resources)
        await createDefaultResources(organization.id);
      },
      beforeDelete: async ({ organization }) => {
        // Cleanup before deletion
        await archiveOrganizationData(organization.id);
      },
    },
    member: {
      afterCreate: async ({ member, organization }) => {
        await notifyAdmins(organization.id, `New member joined`);
      },
    },
    invitation: {
      afterCreate: async ({ invitation, organization, inviter }) => {
        await logInvitation(invitation);
      },
    },
  },
});

Schema Customization

Customize table names, field names, and add additional fields:

organization({
  schema: {
    organization: {
      modelName: "workspace", // Rename table
      fields: {
        name: "workspaceName", // Rename fields
      },
      additionalFields: {
        billingId: {
          type: "string",
          required: false,
        },
      },
    },
    member: {
      additionalFields: {
        department: {
          type: "string",
          required: false,
        },
        title: {
          type: "string",
          required: false,
        },
      },
    },
  },
});

Security Considerations

Owner Protection

The last owner cannot be removed from an organization
The last owner cannot leave the organization
The owner role cannot be removed from the last owner

Always ensure ownership transfer before removing the current owner:

// Transfer ownership first
await authClient.organization.updateMemberRole({
  memberId: "new-owner-member-id",
  role: "owner",
});

// Then the previous owner can be demoted or removed

Organization Deletion

Deleting an organization removes all associated data (members, invitations, teams). Prevent accidental deletion:

organization({
  disableOrganizationDeletion: true, // Disable via config
});

Or implement soft delete via hooks:

organization({
  hooks: {
    organization: {
      beforeDelete: async ({ organization }) => {
        // Archive instead of delete
        await archiveOrganization(organization.id);
        throw new Error("Organization archived, not deleted");
      },
    },
  },
});

Invitation Security

Invitations expire after 48 hours by default
Only the invited email address can accept an invitation
Pending invitations can be cancelled by organization admins

Complete Configuration Example

import { betterAuth } from "better-auth";
import { organization } from "better-auth/plugins";
import { sendEmail } from "./email";

export const auth = betterAuth({
  plugins: [
    organization({
      // Organization limits
      allowUserToCreateOrganization: true,
      organizationLimit: 10,
      membershipLimit: 100,
      creatorRole: "owner",

      // Slugs
      defaultOrganizationIdField: "slug",

      // Invitations
      invitationExpiresIn: 60 * 60 * 24 * 7, // 7 days
      invitationLimit: 50,
      sendInvitationEmail: async (data) => {
        await sendEmail({
          to: data.email,
          subject: `Join ${data.organization.name}`,
          html: `<a href="https://app.com/invite/${data.invitation.id}">Accept</a>`,
        });
      },

      // Hooks
      hooks: {
        organization: {
          afterCreate: async ({ organization }) => {
            console.log(`Organization ${organization.name} created`);
          },
        },
      },
    }),
  ],
});

Two-Factor (2FA)

Setting Up Two-Factor Authentication

When adding 2FA to your application, configure the

twoFactor

plugin with your app name as the issuer. This name appears in authenticator apps when users scan the QR code.

import { betterAuth } from "better-auth";
import { twoFactor } from "better-auth/plugins";

export const auth = betterAuth({
  appName: "My App", // Used as the default issuer for TOTP
  plugins: [
    twoFactor({
      issuer: "My App", // Optional: override the app name for 2FA specifically
    }),
  ],
});

Note: After adding the plugin, run

npx @better-auth/cli migrate

to add the required database fields and tables.

Client-Side Setup

Add the client plugin and configure the redirect behavior for 2FA verification:

import { createAuthClient } from "better-auth/client";
import { twoFactorClient } from "better-auth/client/plugins";

export const authClient = createAuthClient({
  plugins: [
    twoFactorClient({
      onTwoFactorRedirect() {
        window.location.href = "/2fa"; // Redirect to your 2FA verification page
      },
    }),
  ],
});

Enabling 2FA for Users

When a user enables 2FA, require their password for verification. The enable endpoint returns a TOTP URI for QR code generation and backup codes for account recovery.

const enable2FA = async (password: string) => {
  const { data, error } = await authClient.twoFactor.enable({
    password,
  });

  if (data) {
    // data.totpURI - Use this to generate a QR code
    // data.backupCodes - Display these to the user for safekeeping
  }
};

Important: The

twoFactorEnabled

flag on the user is not set to

true

until the user successfully verifies their first TOTP code. This ensures users have properly configured their authenticator app before 2FA is fully active.

Skipping Initial Verification

If you want to enable 2FA immediately without requiring verification, set

skipVerificationOnEnable

twoFactor({
  skipVerificationOnEnable: true, // Not recommended for most use cases
});

Note: This is generally not recommended as it doesn't confirm the user has successfully set up their authenticator app.

TOTP (Authenticator App)

TOTP generates time-based codes using an authenticator app (Google Authenticator, Authy, etc.). Codes are valid for 30 seconds by default.

Displaying the QR Code

Use the TOTP URI to generate a QR code for users to scan:

tsx

import QRCode from "react-qr-code";

const TotpSetup = ({ totpURI }: { totpURI: string }) => {
  return <QRCode value={totpURI} />;
};

Verifying TOTP Codes

Better Auth accepts codes from one period before and one after the current time, accommodating minor clock differences between devices:

const verifyTotp = async (code: string) => {
  const { data, error } = await authClient.twoFactor.verifyTotp({
    code,
    trustDevice: true, // Optional: remember this device for 30 days
  });
};

TOTP Configuration Options

twoFactor({
  totpOptions: {
    digits: 6, // 6 or 8 digits (default: 6)
    period: 30, // Code validity period in seconds (default: 30)
  },
});

OTP (Email/SMS)

OTP sends a one-time code to the user's email or phone. You must implement the

sendOTP

function to deliver codes.

Configuring OTP Delivery

import { betterAuth } from "better-auth";
import { twoFactor } from "better-auth/plugins";
import { sendEmail } from "./email";

export const auth = betterAuth({
  plugins: [
    twoFactor({
      otpOptions: {
        sendOTP: async ({ user, otp }, ctx) => {
          await sendEmail({
            to: user.email,
            subject: "Your verification code",
            text: `Your code is: ${otp}`,
          });
        },
        period: 5, // Code validity in minutes (default: 3)
        digits: 6, // Number of digits (default: 6)
        allowedAttempts: 5, // Max verification attempts (default: 5)
      },
    }),
  ],
});

Sending and Verifying OTP

// Request an OTP to be sent
const sendOtp = async () => {
  const { data, error } = await authClient.twoFactor.sendOtp();
};

// Verify the OTP code
const verifyOtp = async (code: string) => {
  const { data, error } = await authClient.twoFactor.verifyOtp({
    code,
    trustDevice: true,
  });
};

OTP Storage Security

Configure how OTP codes are stored in the database:

twoFactor({
  otpOptions: {
    storeOTP: "encrypted", // Options: "plain", "encrypted", "hashed"
  },
});

For custom encryption:

twoFactor({
  otpOptions: {
    storeOTP: {
      encrypt: async (token) => myEncrypt(token),
      decrypt: async (token) => myDecrypt(token),
    },
  },
});

Backup Codes

Backup codes provide account recovery when users lose access to their authenticator app or phone. They are generated automatically when 2FA is enabled.

Displaying Backup Codes

Always show backup codes to users when they enable 2FA:

tsx

const BackupCodes = ({ codes }: { codes: string[] }) => {
  return (
    <div>
      <p>Save these codes in a secure location:</p>
      <ul>
        {codes.map((code, i) => (
          <li key={i}>{code}</li>
        ))}
      </ul>
    </div>
  );
};

Regenerating Backup Codes

When users need new codes, regenerate them (this invalidates all previous codes):

const regenerateBackupCodes = async (password: string) => {
  const { data, error } = await authClient.twoFactor.generateBackupCodes({
    password,
  });
  // data.backupCodes contains the new codes
};

Using Backup Codes for Recovery

const verifyBackupCode = async (code: string) => {
  const { data, error } = await authClient.twoFactor.verifyBackupCode({
    code,
    trustDevice: true,
  });
};

Note: Each backup code can only be used once and is removed from the database after successful verification.

Backup Code Configuration

twoFactor({
  backupCodeOptions: {
    amount: 10, // Number of codes to generate (default: 10)
    length: 10, // Length of each code (default: 10)
    storeBackupCodes: "encrypted", // Options: "plain", "encrypted"
  },
});

Handling 2FA During Sign-In

When a user with 2FA enabled signs in, the response includes

twoFactorRedirect: true

const signIn = async (email: string, password: string) => {
  const { data, error } = await authClient.signIn.email(
    {
      email,
      password,
    },
    {
      onSuccess(context) {
        if (context.data.twoFactorRedirect) {
          // Redirect to 2FA verification page
          window.location.href = "/2fa";
        }
      },
    }
  );
};

Server-Side 2FA Detection

When using

auth.api.signInEmail

on the server, check for 2FA redirect:

const response = await auth.api.signInEmail({
  body: {
    email: "user@example.com",
    password: "password",
  },
});

if ("twoFactorRedirect" in response) {
  // Handle 2FA verification
}

Trusted Devices

Trusted devices allow users to skip 2FA verification on subsequent sign-ins for a configurable period.

Enabling Trust on Verification

Pass

trustDevice: true

when verifying 2FA:

await authClient.twoFactor.verifyTotp({
  code: "123456",
  trustDevice: true,
});

Configuring Trust Duration

twoFactor({
  trustDeviceMaxAge: 30 * 24 * 60 * 60, // 30 days in seconds (default)
});

Note: The trust period refreshes on each successful sign-in within the trust window.

Security Considerations

Session Management

During the 2FA flow:

User signs in with credentials
Session cookie is removed (not yet authenticated)
A temporary two-factor cookie is set (default: 10-minute expiration)
User verifies via TOTP, OTP, or backup code
Session cookie is created upon successful verification

Configure the two-factor cookie expiration:

twoFactor({
  twoFactorCookieMaxAge: 600, // 10 minutes in seconds (default)
});

Rate Limiting

Better Auth applies built-in rate limiting to all 2FA endpoints (3 requests per 10 seconds). For OTP verification, additional attempt limiting is applied:

twoFactor({
  otpOptions: {
    allowedAttempts: 5, // Max attempts per OTP code (default: 5)
  },
});

Encryption at Rest

TOTP secrets are encrypted using symmetric encryption with your auth secret
Backup codes are stored encrypted by default
OTP codes can be configured for plain, encrypted, or hashed storage

Constant-Time Comparison

Better Auth uses constant-time comparison for OTP verification to prevent timing attacks.

Credential Account Requirement

Two-factor authentication can only be enabled for credential (email/password) accounts. For social accounts, it's assumed the provider already handles 2FA.

Disabling 2FA

Allow users to disable 2FA with password confirmation:

const disable2FA = async (password: string) => {
  const { data, error } = await authClient.twoFactor.disable({
    password,
  });
};

Note: When 2FA is disabled, trusted device records are revoked.

Complete Configuration Example

import { betterAuth } from "better-auth";
import { twoFactor } from "better-auth/plugins";
import { sendEmail } from "./email";

export const auth = betterAuth({
  appName: "My App",
  plugins: [
    twoFactor({
      // TOTP settings
      issuer: "My App",
      totpOptions: {
        digits: 6,
        period: 30,
      },
      // OTP settings
      otpOptions: {
        sendOTP: async ({ user, otp }) => {
          await sendEmail({
            to: user.email,
            subject: "Your verification code",
            text: `Your code is: ${otp}`,
          });
        },
        period: 5,
        allowedAttempts: 5,
        storeOTP: "encrypted",
      },
      // Backup code settings
      backupCodeOptions: {
        amount: 10,
        length: 10,
        storeBackupCodes: "encrypted",
      },
      // Session settings
      twoFactorCookieMaxAge: 600, // 10 minutes
      trustDeviceMaxAge: 30 * 24 * 60 * 60, // 30 days
    }),
  ],
});

better-auth-best-practices

NPX Install

Tags

SKILL.md Content

Better Auth — Best Practices for Common Features

Email/Password

Quick Start

Email Verification Setup

Requiring Email Verification

Client Side Validation

Callback URLs

Password Reset Flows

Security Considerations

Token Security

Session Revocation

Password Requirements

Password Hashing

Custom Hashing Algorithm

See also (related skills — Better Auth family)

Organization plugin

Setting Up Organizations

Client-Side Setup

Creating Organizations

Controlling Organization Creation

Creating Organizations on Behalf of Users

Active Organizations

Getting Full Organization Data

Members

Adding Members (Server-Side)

Assigning Multiple Roles

Removing Members

Updating Member Roles

Membership Limits

Invitations

Setting Up Invitation Emails

Sending Invitations

Creating Shareable Invitation URLs

Accepting Invitations

Invitation Configuration

Roles & Permissions

Checking Permissions

Client-Side Permission Checks

Teams

Enabling Teams

Creating Teams

Managing Team Members

Active Teams

Team Limits

Dynamic Access Control

Enabling Dynamic Access Control

Creating Custom Roles

Updating and Deleting Roles

Lifecycle Hooks

Schema Customization

Security Considerations

Owner Protection

Organization Deletion

Invitation Security

Complete Configuration Example

See also (related skills — Better Auth family)

Two-Factor (2FA)

Setting Up Two-Factor Authentication

Client-Side Setup

Enabling 2FA for Users

Skipping Initial Verification

TOTP (Authenticator App)

Displaying the QR Code

Verifying TOTP Codes

TOTP Configuration Options

OTP (Email/SMS)

Configuring OTP Delivery

Sending and Verifying OTP

OTP Storage Security

Backup Codes

Displaying Backup Codes

Regenerating Backup Codes

Using Backup Codes for Recovery

Backup Code Configuration

Handling 2FA During Sign-In

Server-Side 2FA Detection