Configure features
src/convex/auth.constants.ts exports AUTH_CONSTANTS, the one switch for every feature. The Convex backend (src/convex/auth.ts) reads it to register Better Auth plugins, and the components read it to decide what to show, so a flag turns a feature on in both places. This page lists every key and every environment variable, and links to the page that explains each feature.
Start from the scaffold
The config registry item installs this file with password sign-in only:
Add keys as you need them. When you later run jsrepo update config, keep your version of this file.
A change reaches the backend when Convex deploys it. Locally, keep npx convex dev running; in production, deploy the backend and the app together.
A fuller configuration, with password and magic-link sign-in, GitHub, organizations and branding:
Sign-in methods
providers is the only required key. Each sign-in method is a boolean and defaults to off.
| Key | Turns on | Needs |
|---|---|---|
password | Sign-up and sign-in with email and password. | Nothing. With sendEmails: true, users must verify their address before they can sign in. |
emailOTP | Sign-in with a one-time code sent by email. | sendEmails: true |
magicLink | Sign-in with a link sent by email. | sendEmails: true |
The social providers are booleans in the same object: apple, atlassian, discord, dropbox, facebook, figma, github, gitlab, google, huggingface, kakao, kick, line, linear, naver, notion, paypal, reddit, roblox, salesforce, slack, spotify, tiktok, twitch, vk, x and zoom. Each one needs OAuth credentials in your Convex environment. Social providers lists their environment variable names and callback URLs.
Feature flags
Each flag is a boolean and defaults to off.
| Key | Turns on | Read more |
|---|---|---|
sendEmails | Transactional email through Resend: verification on password sign-up, password reset, one-time codes, magic links and invitations. Required by emailOTP, magicLink and organizations. | Sending emails |
validateEmails | A deliverability check with Reoon when someone enters an email address that has no account yet. | Validate emails |
organizations | Better Auth’s organization plugin, a personal organization for every new user, and the organization switcher and profile in the root layout. | Organizations |
apiKeys | Better Auth’s API key plugin and the API keys section in the user profile. | API keys |
deviceAuthorization | Better Auth’s device authorization plugin and the page where a signed-in user approves a device. | Device authorization |
admin | Better Auth’s admin plugin, the /admin dashboard and the banner shown while an admin impersonates a user. | Admin |
Branding and legal links
| Key | Type | Default | Where it shows |
|---|---|---|---|
brandName | string | 'self hosted Auth' | The sign-in heading, the header of every email, and the subject lines of the magic-link and invitation emails. |
brandTagline | string | 'Plug & Play Auth Widgets for your application.' | Below the sign-in heading, and in the email footer. |
terms | string | none | A “Terms” link below the sign-in form. |
privacy | string | none | A “Privacy Policies” link below the sign-in form. |
Set brandName and brandTagline: the defaults are placeholder text, and the sign-in form shows them. terms and privacy take any URL, relative (/terms) or absolute. When neither is set, the sign-in form shows no legal line.
Features that need sendEmails
AuthConstants is a union of two shapes. emailOTP, magicLink and organizations only type-check next to sendEmails: true, so TypeScript rejects this:
Turning sendEmails on changes more than the email features:
- Password sign-up sends a verification email, and the link in it signs the user in.
- Password sign-in is refused until the address is verified. The form says “Please verify your email address.” and doesn’t send a new link.
- The password step shows “Forgot password?“.
- Sending needs
RESEND_API_KEYandEMAIL_SEND_FROMin Convex. WithoutEMAIL_SEND_FROM, every email fails.
Always on
These Better Auth options are set in src/convex/auth.ts and don’t depend on a flag:
- Users can delete their account from the user profile.
- Users can change their email address. This sends an email whatever
sendEmailssays, so configure Resend before you ship the user profile. See Sending emails. - A user can link a social account whose email differs from their own (
accountLinking.allowDifferentEmails).
Environment variables
Convex
Set these on each Convex deployment (development, preview and production have separate values) with npx convex env set NAME value, or in the Convex dashboard.
| Variable | Needed for | Read more |
|---|---|---|
BETTER_AUTH_SECRET | Always. Better Auth signs and encrypts with it. | Getting startedGetting started |
BETTER_AUTH_ALLOWED_HOSTS | Always. A comma-separated list of the hosts your app runs on, * allowed, such as localhost:*,127.0.0.1:*. | Getting started, Vercel, Cloudflare |
BETTER_AUTH_FALLBACK_URL | Auth calls that run without a request, such as scheduled functions. Required for deviceAuthorization. | Getting started, Device authorization |
BETTER_AUTH_BASE_URL_PROTOCOL | Optional. http or https forces the protocol of the URLs Better Auth builds, and with it whether cookies are __Secure- and Secure. Without it, each request decides the protocol, and cookies are Secure only with an https BETTER_AUTH_FALLBACK_URL. Set https in your preview defaults. auto leaves cookies without Secure. | Getting started, Vercel, Cloudflare |
RESEND_API_KEY | sendEmails | Sending emails |
EMAIL_SEND_FROM | sendEmails, and email changes in the user profile | Sending emails |
RESEND_WEBHOOK_SECRET | Optional. Resend’s delivery events. | Sending emails |
BRAND_LOGO_URL | Optional. A logo in the email header. | Sending emails |
REOON_EMAIL_VERIFIER_TOKEN | validateEmails | Validate emails |
DEVICE_AUTHORIZATION_CLIENT_ID | deviceAuthorization | Device authorization |
ADMIN_USER_IDS | admin. Comma-separated Better Auth user ids of the first admins. | Admin |
<PROVIDER>_CLIENT_ID, <PROVIDER>_CLIENT_SECRET | Each social provider. TikTok uses TIKTOK_CLIENT_KEY instead of a client id. | Social providers |
App
npx convex dev writes these to .env.local. Your hosting platform needs them too.
| Variable | Value |
|---|---|
PUBLIC_CONVEX_URLNEXT_PUBLIC_CONVEX_URL | The deployment URL, ending in .convex.cloud. |
PUBLIC_CONVEX_SITE_URLNEXT_PUBLIC_CONVEX_SITE_URL, or CONVEX_SITE_URL | The HTTP actions URL, ending in .convex.site, which serves the Better Auth routes. |