Authentication

Built-in authentication powered by Better Auth. Configure strategies, roles, two-factor authentication, and email templates.

Basic Setup

Start with the simplest auth config: email and password with a default role.

YAML
auth:
  strategies:
    - type: emailAndPassword
  defaultRole: member

Strategies

Choose one or more authentication strategies to offer your users.

PropertyDescription
emailAndPasswordTraditional email + password. Supports signup, login, password reset, and email verification.
magicLinkPasswordless authentication via a one-time link sent by email. No password to remember.
oauthSocial login via external providers. Supports: google, github, microsoft, slack, gitlab.

Strategy Options

Each strategy type accepts additional configuration properties.

PropertyDescription
emailAndPassword.minPasswordLengthMinimum password length (6–128, default: 8).
emailAndPassword.maxPasswordLengthMaximum password length (8–256, default: 128).
emailAndPassword.requireEmailVerificationRequire email verification before sign-in (default: false).
emailAndPassword.autoSignInAuto sign in after signup (default: true).
magicLink.expirationMinutesMagic link expiration time in minutes (default: 15).
YAML
auth:
  strategies:
    - type: emailAndPassword
      minPasswordLength: 12
      requireEmailVerification: true
    - type: magicLink
      expirationMinutes: 30

Allow Sign-Up

Controls whether users can self-register. Set to false to restrict user creation to admins only.

YAML
auth:
  allowSignUp: false
  strategies:
    - type: emailAndPassword

Adding OAuth

Add social login providers alongside emailAndPassword. Multiple strategies can coexist.

YAML
auth:
  strategies:
    - type: emailAndPassword
    - type: magicLink
    - type: oauth
      providers:
        - google
        - github

Environment variables required

OAuth providers require AUTH_SECRET and provider-specific CLIENT_ID / CLIENT_SECRET environment variables.

Roles & Permissions

Three built-in roles: admin, member, viewer. Define custom roles with name, description, and optional level (hierarchy ordering). Set defaultRole for new users. First user automatically becomes admin.

YAML
auth:
  strategies:
    - type: emailAndPassword
  defaultRole: member
  roles:
    - name: editor
      description: Can edit content
      level: 30
    - name: reviewer
      description: Can approve changes
      level: 20

admin

Full access to all features, user management, and settings.

member

Can create, read, and update records. Cannot manage users.

viewer

Read-only access. Cannot create or modify records.

Two-Factor Auth

Optional TOTP-based 2FA. Enable with twoFactor: true or pass an object with issuer, backupCodes, digits, and period options.

YAML
# Boolean shorthand
auth:
  strategies:
    - type: emailAndPassword
  twoFactor: true

# Object form with options
auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: "MyApp"
    backupCodes: true
    digits: 6
    period: 30

Email Templates

Customizable emails for verification, resetPassword, magicLink, emailOtp, twoFactorBackupCodes, welcome, and accountDeletion. Supports $name, $url, $email variable substitution in subject and text.

YAML
auth:
  strategies:
    - type: emailAndPassword
  emailTemplates:
    verification:
      subject: "Verify your email, $name"
      text: "Click here to verify: $url"
    resetPassword:
      subject: "Reset your password"
      text: "Hi $name, reset here: $url"
    magicLink:
      subject: "Your sign-in link"
      text: "Click to sign in: $url"
    emailOtp:
      subject: "Your one-time code"
      text: "Your code is: $code"
    twoFactorBackupCodes:
      subject: "Your backup codes"
      text: "Save these backup codes: $codes"
    welcome:
      subject: "Welcome to $organizationName"
      text: "Hi $name, welcome aboard!"
    accountDeletion:
      subject: "Account deletion confirmation"
      text: "Hi $name, your account has been deleted."
PropertyDescription
$nameThe recipient's display name.
$urlThe action URL (verification link, reset link, or magic link).
$emailThe recipient's email address.
$organizationNameThe organization name (for invitation emails).
$inviterNameThe name of the person who sent the invitation.
Tables & FieldsLanguages