Better Auth Documentation

The 'active organization' is stored in the user's session. Once set, subsequent API calls (like listMembers or inviteMember) will automatically scope to this organization if an organizationId is not explicitly provided. Use setActive to switch the current context.

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

Better Auth supports direct database connections and ORM adapters.

Direct Connections

You can pass instances of:

• pg.Pool (Postgres)
• mysql2 pool
• better-sqlite3 or bun:sqlite (SQLite)
• postgres (postgres.js)
• @neondatabase/serverless

ORM Adapters

Import adapters from specific paths:

• better-auth/adapters/drizzle
• better-auth/adapters/prisma
• better-auth/adapters/mongodb

Drizzle Configuration

When using Drizzle, provide the provider value ("pg", "mysql", or "sqlite") which must match your driver.

⚠️ Critical: Model vs Table Names

Better Auth uses adapter model names, NOT underlying database table names. If your Prisma model is User but the table is users, use modelName: "user" in your configuration.

Trusted Devices

When verifying a code, pass trustDevice: true to remember the device. The default trust duration is 30 days, controlled by trustDeviceMaxAge in the server config. This duration is refreshed on every sign-in.

Session Management

2FA uses a temporary cookie during the verification phase. You can control its lifespan using twoFactorCookieMaxAge (default is 600 seconds / 10 minutes).

Rate Limiting

• Global: 3 requests per 10 seconds for all 2FA endpoints.
• OTP Specific: You can set allowedAttempts in otpOptions to limit attempts per specific code.

Teams allow grouping members within an organization.

1. Enable: Set teams: { enabled: true } in the organization() plugin config.
2. Create: Use authClient.organization.createTeam({ name: '...' }).
3. Manage Members: Use addTeamMember({ teamId, userId }) and removeTeamMember({ teamId, userId }). Note that a user must be a member of the organization before they can be added to a team.
4. Set Active Team: Use setActiveTeam({ teamId }) to switch the current team context.

// Enable teams in server config
organization({
  teams: {
    enabled: true
  }
});

// Client-side team management
await authClient.organization.createTeam({ name: "Engineering" });
await authClient.organization.addTeamMember({ teamId: "team-id", userId: "user-id" });

To add authentication to your project, install the core package. Depending on your requirements, you may also need to install specific scoped packages for features like Passkeys, SSO, or Stripe integration.

Core package:

npm install better-auth

Scoped packages:

• @better-auth/passkey: WebAuthn/Passkey auth
• @better-auth/sso: SAML/OIDC enterprise SSO
• @better-auth/stripe: Stripe payments
• @better-auth/scim: SCIM user provisioning
• @better-auth/expo: React Native/Expo

Use the explain-error command to receive a comprehensive breakdown of a specific Better Auth error. The command accepts either a specific error code or a full error message as an argument.

For a given error, the tool provides:

• A plain English explanation of the error's meaning.
• A list of common causes.
• Specific solutions and handling recommendations.
• Production-ready code examples demonstrating how to catch the error, display user-friendly messages, and determine if a retry is appropriate.
• Related error codes for context.
• Links to the official Better Auth documentation.

# Usage pattern
explain-error [error_code or error_message]

If the default roles (owner, admin, member) are insufficient, you can enable Dynamic Access Control using the @better-auth/organization/addons package. This allows you to create custom roles with granular permissions.

Workflow:

1. Enable dynamicAccessControl: { enabled: true } in the organization() plugin.
2. Create a role using authClient.organization.createRole and define its permission object (e.g., member: ['read']).

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

// Server config
organization({
  dynamicAccessControl: {
    enabled: true
  }
});

// Client-side: Create custom role
await authClient.organization.createRole({
  role: "moderator",
  permission: {
    member: ["read"],
    invitation: ["read"],
  },
});

Better Auth requires a catch-all route handler to manage authentication requests. The implementation varies by framework:

Note for Next.js Server Components: You must add the nextCookies() plugin to your server auth configuration.

Organizations can be created via the client (where the creator is automatically assigned the owner role) or via the server API (for administrative actions).

Client-side creation: Use authClient.organization.create. Requires name and slug.

Server-side creation (on behalf of users): Use auth.api.createOrganization. This requires a userId for the new owner. Note that when using userId, you cannot also pass session headers.

// Client-side
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" },
  });
};

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