Builder Toolkit · 11 / 11

OAuth Basics

Understand what "Sign in with Google" actually delegates, how redirect URLs work, and why most setups fail.

OAuth Basics

What this is

OAuth is the system behind "Sign in with Google" and similar buttons.

Instead of your app storing a password, the provider confirms who the person is and hands your app a token saying so.

The one idea

Your app never sees the password. It receives proof of identity from someone the user already trusts.

Why it matters

Storing passwords safely is genuinely hard, and getting it wrong is a serious problem for real users. Delegating it removes that burden entirely.

It is also the setup beginners most often abandon, almost always for the same reason: one mismatched redirect URL, producing an error that explains nothing.

What to do

Follow the flow

Copy

User clicks sign in
  → sent to the provider
  → user approves
  → provider redirects back with a code
  → your app exchanges the code for a session

The failure is nearly always at the fourth arrow. The provider will only redirect to an address you registered in advance, exactly as written.

Register every redirect URL

You need one for each place your app runs:

Environment	Example
Local development	`http://localhost:3000/auth/callback`
Production	`https://yourdomain.com/auth/callback`

Both must be registered before either works. These are matched character for character. A trailing slash, http instead of https, or www present in one and absent in the other all count as different.

The mismatch error is deliberately vague

Providers keep these messages generic on purpose, so attackers learn nothing. When you see a redirect mismatch, compare the two strings character by character rather than searching the error text.

Set it up

Create OAuth credentials in the provider's developer console.
Register every redirect URL, local and production.
Copy the client ID and client secret.
Put them in your environment variables, following Environment Variables.
Enable the provider in your auth service, such as Supabase Auth.
Test locally first, then on the deployed site.

The client secret is server-only. It never gets a public prefix and never appears in browser code.

Do this now

Write out your two redirect URLs on paper, exactly as your app will send them. Most setup failures are visible at this step, before you touch a console.

Check yourself

I can explain what my app receives instead of a password.
I have registered both local and production redirect URLs.
My client secret is server-only and never in browser code.
I tested signing in locally before deploying.
I know a mismatch error means the strings differ, not that the code is broken.

Know what you are asking for

Providers let you request scopes: the specific things you want access to. Request the minimum. Asking for a user's contacts to run a login screen is both unnecessary and a reason people abandon signup.

If login works locally but not live

The production redirect URL is missing, misspelled, or was registered with a different protocol. Check that before changing any code.

Common mistakes

Registering only the local redirect URL, then finding login broken after deploying.
Protocol or trailing-slash differences between the registered and actual URL.
Putting the client secret in a public environment variable.
Requesting far more scopes than the app needs.
Adding login to a project that has nothing behind it yet.
Testing only in a logged-in browser, so the signed-out path is never checked.

Next step

You have the foundations. Take them back to your build in Build in Your Workspace.