Set up OAuth

OAuth lets users sign in with their Google, GitHub, or Vercel account. Neon Auth handles the OAuth flow and creates a session after authorization.

Development mode

Google OAuth is enabled by default with shared credentials for development and testing. You can start using Google sign-in immediately without any configuration.

For production, configure your own OAuth app credentials for each provider you use. See Production setup below.

Sign in with OAuth

Call signIn.social() with your provider ("google", "github", or "vercel"). The SDK sends the user to the provider's sign-in page. After the user authorizes, the provider redirects to Neon Auth's OAuth callback route (see Production setup), then Neon Auth redirects the browser to your callbackURL (must use a trusted domain in production).

import { authClient } from './auth';

const handleGoogleSignIn = async () => {
  try {
    await authClient.signIn.social({
      provider: "google",
      callbackURL: window.location.origin,
    });
  } catch (error) {
    console.error("Google sign-in error:", error);
  }
};

Handle the callback

After the OAuth exchange completes, Neon Auth redirects the browser to your callbackURL. Then load or refresh session state in your client:

import { authClient } from './auth';

useEffect(() => {
  authClient.getSession().then(({ data }) => {
    if (data?.session) {
      setUser(data.session.user);
    }
    setLoading(false);
  });
}, []);

Custom redirect URLs

Specify different URLs for new users or errors:

await authClient.signIn.social({
  provider: "google", // or "github", "vercel"
  callbackURL: "/dashboard",
  newUserCallbackURL: "/welcome",
  errorCallbackURL: "/error",
});

Production setup

For production, configure your own OAuth app credentials. GitHub and Vercel OAuth require custom credentials, while Google OAuth works with shared credentials for development but should use custom credentials in production.

1. Register redirect URIs with each provider

Neon Auth uses Better Auth callback routes. For each OAuth provider you enable, register a redirect URI with this shape:

{NEON_AUTH_BASE_URL}/callback/{provider}

Use the Auth base URL from the Neon Console for that branch. In your app it is usually the NEON_AUTH_BASE_URL or VITE_NEON_AUTH_URL value, or the URL you pass to createAuthClient. Do not add a trailing slash before /callback.

Replace {provider} with google, github, or vercel.

Example authorized redirect URI for Google:

https://ep-example.neonauth.us-east-2.aws.neon.tech/neondb/auth/callback/google

Whether you use the Next.js auth proxy (app/api/auth/[...path]/route.ts) or call Neon Auth from the browser, the provider redirects to {NEON_AUTH_BASE_URL}/callback/{provider} for that branch.

Google Cloud Console

Create an OAuth client with application type Web application. Under Authorized redirect URIs, add {NEON_AUTH_BASE_URL}/callback/google for each branch or environment (production, local testing against a branch, previews). Under Authorized JavaScript origins, include origins where your UI runs (for example http://localhost:5173, https://myapp.com) when Google asks for them, and include your Neon Auth origin (the scheme and host of NEON_AUTH_BASE_URL) if required.

GitHub

Set Authorization callback URL to {NEON_AUTH_BASE_URL}/callback/github.

Vercel

Follow Vercel's OAuth app docs and register {NEON_AUTH_BASE_URL}/callback/vercel.

2. Add trusted domains for your app

Before testing production OAuth, add every origin you pass as callbackURL (and related URLs) to Neon Auth's allowlist. See Configure trusted domains.

3. Create OAuth apps and paste credentials into Neon

1. Create OAuth apps with your providers:
   • Google OAuth setup (see Google OAuth branding below before going live)
   • GitHub OAuth setup
   • Vercel OAuth setup
2. In the Neon Console, open your project, select the branch, open Auth, then enter the Client ID and Client Secret for each provider.

Neon Auth will use your configured credentials for that branch.

Branches and preview deployments

Each branch has its own NEON_AUTH_BASE_URL. Register {NEON_AUTH_BASE_URL}/callback/google (and other providers you use) for every branch you test against (for example preview databases).

For preview deployments, trusted domains support wildcard patterns (for example https://*.my-app-preview.vercel.app), so you can cover many preview hosts without listing each one. See Configure trusted domains, Branching authentication, and the API for trusted domains.

Google OAuth branding

When using your own Google OAuth credentials, users will see a consent screen before signing in. Google shows a Continue to label that uses the hostname from your OAuth redirect URI (see Production setup), typically the Neon-managed host from your NEON_AUTH_BASE_URL.

Without completing the OAuth consent screen branding (app name, support email, and authorized domains in Google Cloud Console), the consent UI can look generic or confusing even when your Client ID and Client Secret are correct.

To show your app's name on the consent screen:

1. Go to Google Cloud Console → OAuth consent screen
2. Fill in the required app information:
   • App name: the name users will see on the consent screen
   • User support email: a contact email for users with auth questions
   • Developer contact information: your email address (not shown to users)
3. Under Authorized domains, add your app's domain (for example, myapp.com)
4. Save your changes

• 

  Email Verification

  Add email verification