Help Center/Admin Operations/How to switch sign-in to Better Auth (Neon Auth) and back
Admin Operations•Last updated: 2026-10-20•4 min read

How to switch sign-in to Better Auth (Neon Auth) and back

Operator runbook: the Neon console settings the platform relies on, the one environment switch that moves sign-up and sign-in from Clerk to Better Auth, and how to roll back.

Have questions or need step-by-step guidance on this topic?

Ask AI Copilot

Step-by-Step Procedure

1

Check the Neon Auth settings

In the Neon console (project > Auth): email and password sign-up on, "Verify at sign-up" on, verification METHOD = verification code (keep it on code: the platform's own email adds the link), custom SMTP set to Resend as a fallback (host smtp.resend.com, port 465, user "resend", password = a Resend API key, sender on a Resend-verified domain), and the app origins (https://www.infin8.cc and http://localhost:3000) listed as trusted domains.

2

Set the environment variables

NEON_AUTH_BASE_URL (the Auth URL from the console; its /.well-known/jwks.json verifies webhook signatures), NEON_AUTH_COOKIE_SECRET (32+ characters), BETTER_AUTH_URL = https://www.infin8.cc (every emailed link is built from it, never from a request), RESEND_API_KEY and EMAIL_FROM (a sender on the Resend-verified domain, e.g. "INFIN8 <noreply@infin8.cc>"). Optional: NEON_AUTH_JWKS_URL, BETTER_AUTH_RESET_METHOD=link to send reset links instead of codes, BETTER_AUTH_SEND_CODE_ON_SIGNIN=false if the console already emails a code when an unconfirmed member signs in.

3

Apply the additive table

Run "npm run db:apply:better-auth" once. It creates i8_pending_signup_profiles only; nothing is changed or removed. The webhook creates its own small table, i8_neon_auth_webhook_events (event ids only, no codes), on first use.

4

Flip the switch and redeploy

Set AUTH_PROVIDER=better and redeploy. The sign-in and sign-up pages now show the platform's own forms.

5

Turn on the email webhook (code AND link in every email)

Only after the deploy with RESEND_API_KEY and EMAIL_FROM is live: Neon console > Auth > Configuration > Webhooks. Enable it, URL https://www.infin8.cc/api/v1/auth/neon-webhook, enabled events send.otp and send.magic_link (user.created is optional and ignored), timeout 8 seconds (5 to 10). Save. From now on Neon stops sending its own code-only email and the platform sends one branded email with the 6-digit code and a "Confirm my email" button (reset emails: code and a "Choose a new password" button).

6

Test it

Sign up with a fresh address: you land on "Verify your email" and receive one INFIN8 email with a code and a button. Press the button in a private window (it should confirm and sign you in), then repeat with another address typing the code instead. Then use "Forgot password?" and check the reset email also has both. In Vercel logs, [neon-webhook] lines show "delivered" with the event id only. To undo, disable the webhook in the console: Neon goes back to its own code-only email at once.

7

Roll back if needed

Remove AUTH_PROVIDER (or set it to clerk) and redeploy. Clerk sign-in returns unchanged. Members who joined through Better Auth keep their INFIN8 accounts; they sign up once in Clerk with the same email and, after Clerk verifies it, the Clerk exchange links them to their existing identity.

Expected Operational Outcome

Members sign up, confirm their email and sign in through the platform's own forms, and their INFIN8 identity is provisioned once.

Troubleshooting & Failure Modes

Symptom: Sign-up answers BETTER_AUTH_NOT_CONFIGURED
Likely Cause: NEON_AUTH_BASE_URL or NEON_AUTH_COOKIE_SECRET is missing or too short.
Resolution: Set both and redeploy.
Symptom: Confirmation emails do not arrive
Likely Cause: With the webhook on: RESEND_API_KEY / EMAIL_FROM missing (the webhook answers 503 and logs "mail provider not configured") or the Resend domain is not verified. With the webhook off: the Neon custom SMTP provider is wrong.
Resolution: Check the [neon-webhook] lines in the Vercel logs, the env vars and the domain status in Resend. Disabling the webhook in the console restores Neon's own code-only email immediately.
Symptom: Webhook log says "rejected" with INVALID_SIGNATURE or STALE_TIMESTAMP
Likely Cause: NEON_AUTH_BASE_URL points at a different Neon Auth project than the one sending, or the call was not from Neon.
Resolution: Set NEON_AUTH_BASE_URL to this project's Auth URL and redeploy. Nothing is sent for a rejected call.
Symptom: The email has the code but no button
Likely Cause: BETTER_AUTH_URL and NEXT_PUBLIC_APP_URL are both unset or not https, so no safe link could be built.
Resolution: Set BETTER_AUTH_URL=https://www.infin8.cc and redeploy.

Was this guide helpful?

Help us refine our platform documentation