Skip to main content
View as Markdown

Authentication Strategies

auth.strategies is a required, non-empty array declaring how users authenticate. Each entry is a discriminated union keyed by type. At least one strategy is required, and no two entries may share the same type.

auth:
  strategies:
    - type: emailAndPassword
    - type: oauth
      providers: [google, github]
type Description
emailAndPassword Traditional credential-based sign-up and sign-in.
magicLink Passwordless sign-in via a one-time email link.
oauth Social login with external identity providers (Google, GitHub, …).

Email & Password

The most common strategy. Credentials are validated server-side and a session is issued on success.

auth:
  strategies:
    - type: emailAndPassword
      minPasswordLength: 12
      maxPasswordLength: 128
      requireEmailVerification: true
      autoSignIn: true
Property Description
minPasswordLength Minimum password length, 6–128. Defaults to 8.
maxPasswordLength Maximum password length, 8–256. Defaults to 128.
requireEmailVerification Boolean. When true, users must verify their email before sign-in. Defaults to false.
autoSignIn Boolean. When true, users are signed in automatically after sign-up. Defaults to true.

When requireEmailVerification: true, a verification email is sent on sign-up using the verification template (see Email Templates).

Passwordless authentication. The user enters their email, receives a one-time link, and is signed in by clicking it. Requires SMTP to be configured (see Environment Variables).

auth:
  strategies:
    - type: magicLink
      expirationMinutes: 30
Property Description
expirationMinutes Link lifetime in minutes (positive integer). Defaults to 15.

The link body is rendered from the magicLink email template when provided.

Email-OTP

Email-OTP delivers a numeric one-time code by email instead of a link. It is not a strategy entry — it activates when you define the emailOtp email template:

auth:
  strategies:
    - type: emailAndPassword
  emailTemplates:
    emailOtp:
      subject: Your sign-in code
      text: 'Your verification code is $code. It expires shortly.'

The presence of emailTemplates.emailOtp mounts the email-OTP plugin. The $code variable is substituted with the generated one-time code.

Social / OAuth Providers

Federated login through external identity providers. Credentials are never in the schema — they load from environment variables.

auth:
  strategies:
    - type: oauth
      providers: [google, github, microsoft, slack, gitlab]
Property Description
providers Non-empty array of provider identifiers. Credentials loaded from env vars.

Supported providers:

Provider Use case
google Google Workspace integration.
github Developer authentication.
microsoft Enterprise / Azure AD.
slack Workspace communication.
gitlab Developer / CI-CD integration.

Each enabled provider needs a credential pair in the environment:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

The general form is {PROVIDER}_CLIENT_ID and {PROVIDER}_CLIENT_SECRET. Callback URLs are derived from BASE_URL. See Environment Variables.

Registration Control

auth.allowSignUp decides whether the public can create their own accounts.

auth:
  allowSignUp: false
  strategies:
    - type: emailAndPassword
Value Behavior
true (default) Anyone can self-register via the enabled strategies.
false Self-registration is disabled. Only admins create users via POST /api/auth/admin/create-user or invitations.

When self-registration is off, admins onboard users with single-use invitation tokens:

auth:
  allowSignUp: false
  strategies:
    - type: emailAndPassword
  invitationTokenExpiry: 7d
Property Description
invitationTokenExpiry Lifetime of tokens from POST /api/auth/admin/invite-user. Duration string (72h, 7d) or milliseconds. Defaults to 72h.

Email Templates

auth.emailTemplates customizes the subject and body of authentication emails. Every template is optional — Better Auth supplies sensible defaults. Defining the emailOtp template additionally enables the email-OTP flow.

auth:
  strategies:
    - type: emailAndPassword
    - type: magicLink
  emailTemplates:
    verification:
      subject: Verify your email for MyApp
      text: 'Hi $name, confirm your email: $url'
    resetPassword:
      subject: Reset your password
      text: 'Reset your password: $url'
      html: '<p>Click <a href="$url">here</a> to reset your password.</p>'
    magicLink:
      subject: Your sign-in link
      text: 'Sign in to MyApp: $url'
Template When it is sent
verification Email verification after sign-up.
resetPassword Password-reset request.
magicLink Magic-link sign-in.
emailOtp Email one-time code (its presence enables email-OTP).
twoFactorBackupCodes Two-factor backup codes delivery.
welcome Welcome email after verification.
accountDeletion Account-deletion confirmation.
invitation Admin-issued invitation (passwordless onboarding).

Each template accepts a required subject and optional text and/or html bodies. Bodies support $variable substitution:

Variable Meaning
$url Action link (verify, reset, magic link, invitation accept).
$name Recipient's name.
$email Recipient's email address.
$code One-time code (email-OTP).
$organizationName Organization name (invitations).
$inviterName Name of the admin who sent the invitation (admin invitations only).