What is /__/auth/handler in Firebase Auth?

What the handler does in the sign-in flow

1. Your app calls signInWithPopup() or signInWithRedirect().
2. The Firebase JS SDK builds the URL https://${authDomain}/__/auth/handler and opens it in the popup or the current tab.
3. The handler redirects to the provider. In Firebase's words, "authDomain hosts the sign-in helper code that redirects to the Identity Provider, which, on success, redirects back to the app domain."
4. The provider sends the user back to the handler, which passes the result to your app.

The SDK also loads a sibling page, https://${authDomain}/__/auth/iframe, in the background. That is why any setup that moves authDomain must serve the whole /__/auth/* path, not just the handler. If authDomain isn't set, the SDK throws auth/auth-domain-config-required before it gets this far. For the setting itself, see what Firebase authDomain is.

What the handler URL contains

A real handler URL carries query parameters that the SDK adds. From the SDK source, they can include:

An App Check token, if you use App Check, is passed in the URL fragment (#fac=…). Seeing your apiKey in this URL is expected: Firebase says API keys for its services "only identify your Firebase project and app to those services."

What it serves

/__/auth/* is part of Firebase Hosting's reserved namespace. Firebase says Authentication "uses the reserved namespace to provide special JavaScript and HTML to complete authentication with providers via OAuth." Every Firebase project gets it on <project-id>.firebaseapp.com, the subdomain Firebase provisions when the project is created, whether or not you use Firebase Hosting for your app.

Firebase's self-hosting instructions list the files behind it: handler, handler.js, experiments.js, iframe, iframe.js, links, links.js, plus /__/firebase/init.json. So the handler is a small HTML page that loads Firebase's own scripts. It is not a page you build, and your app's router should never answer this path.

Why it must be an authorized redirect URI

Google only sends an OAuth response to a redirect URI registered on the OAuth client. If the redirect_uri "doesn't match an authorized redirect URI for the provided client_id you will get a redirect_uri_mismatch error," and "the http or https scheme, case, and trailing slash ('/') must all match."

For the default setup, the OAuth web client lists:

https://<project-id>.firebaseapp.com/__/auth/handler
https://<project-id>.web.app/__/auth/handler

Firebase's FAQ shows these two values when you rebuild a missing web client by hand, and notes that "Some Firebase Hosting domains don't use Firebase project ID," so copy the exact host. When you move authDomain to your own domain, add https://<your domain>/__/auth/handler as well. Firebase says "the trailing /__/auth/handler is important."

To edit the list (labels as of Oct 2026): Google Cloud console → Google Auth Platform → Clients (older guides: APIs & Services → Credentials) → open the web client whose ID matches the one in Firebase's Google provider settings → Authorized redirect URIs. Google says changes can take "5 minutes to a few hours" to apply.

Common errors and fixes

About the "not authorized" message: Firebase's FAQ notes that "the hostname of the page where you saw this error is your current authDomain." If that host is already listed, its next suspect is an invalid or deleted API key.

About service workers: Firebase warns that a PWA's navigation fallback must exclude this path. "You must disable any fallbacks for the /__ namespace," and "you should not intercept these requests in your service worker."

How to confirm the handler is reachable

1. Open the default handler. Run curl -s https://<project-id>.firebaseapp.com/__/auth/handler. You should get a short HTML page (Firebase's handler file), not an error page.
2. If you use your own domain, compare the two. A transparent proxy returns the same page:

bash curl -s https://<project-id>.firebaseapp.com/__/auth/handler > firebase.html curl -s https://<your domain>/__/auth/handler > mine.html diff firebase.html mine.html && echo "Same handler"

3. Check the OAuth client lists the handler URL for the exact host in your authDomain.
4. Run a sign-in in a private window and watch the popup or address bar: it should pass through https://<authDomain>/__/auth/handler and return to your app.

Using the Auth emulator? With connectAuthEmulator(), the SDK opens the emulator's own emulator/auth/handler path instead of https://<authDomain>/__/auth/handler.