Authorized domains are the domain names an identity provider, email platform, or hosted service is allowed to trust for redirects, sign-ins, links, and ownership-sensitive actions. In practice, they are the difference between a clean production launch and a login screen that says your domain is not allowed five minutes before users arrive.
The annoying part is that the setting usually looks small. One text box. One domain. Maybe a DNS record. Then the real app shows up with www, a bare apex domain, a preview URL, a dashboard subdomain, an API domain, and an OAuth callback that only works locally. Your launch checklist just grew legs.
This guide is for builders who are shipping real apps, not filling out a glossary. We will treat authorized domains as an operational boundary: what should be trusted, what should never be trusted, and how to keep auth, email, and custom domains from turning into a dashboard scavenger hunt.
Table of contents
- The short version
- Why authorized domains exist
- The three places this setting shows up
- A production checklist before launch
- Common mistakes that break sign-in
- How to handle preview and staging URLs
- Where RunxBuild fits in the workflow
- FAQ
The short version
Use authorized domains to allow only the domains your app actually controls and serves in production or trusted staging. Add the apex domain, the www variant if you use it, required subdomains, and any platform-provided URL that must participate in sign-in, email verification, callbacks, or protected routes.
Do not add wildcard domains casually. Do not authorize a domain just because a local test failed. Do not leave old staging domains trusted after they stop being used. Every trusted domain is a small permission boundary. Treat it that way.
For most apps, the clean setup looks like this:
example.comfor the main sitewww.example.comif users can reach itapp.example.comfor the logged-in productapi.example.comonly if an auth provider or redirect flow needs it- one staging domain if you genuinely test auth outside production
That is enough. The goal is not to collect domains like stickers on a laptop.
Why authorized domains exist
Authentication and email systems need to know which domains are allowed to speak for your app. Without that list, a malicious or misconfigured app could redirect users to a lookalike domain, send verification links from the wrong host, or claim an identity flow it does not own.
A domain allowlist protects several things at once:
- OAuth redirect flows
- email verification and password reset links
- app branding and consent screens
- hosted login pages
- protected backend routes
- single sign-on callbacks
- internal tools that sit behind identity-aware access
The official OAuth 2.0 documentation for web server apps is a useful reference because it shows the same principle in a stricter form: redirect URIs must match what the provider expects. The provider is not being picky for fun. It is preventing credentials and tokens from being sent somewhere unexpected.
That same idea applies to email platforms and hosted dashboards. If a service sends a password reset link for your app, it needs to know which host is legitimate. A prototype without that boundary is just a mystery with a URL.
The three places this setting shows up
The phrase authorized domains is used differently across products, but the operational pattern is the same.
Auth and OAuth providers
This is the most common version. Your identity provider asks for domains or redirect URLs that are allowed to complete sign-in. If https://app.example.com/auth/callback is not on the list, the login flow fails even if your code is perfect.
This is why local development works and production fails. Your local callback might be trusted, while the new custom domain is not.
Email and sender verification
Email platforms usually ask you to verify a sending domain with DNS records. That is not always called an authorized domain, but it solves the same trust problem. The platform needs proof that you control the domain before it sends mail on your behalf.
For production apps, this affects transactional email: invites, receipts, password resets, verification links, and alerts. If those links point at the wrong host, users do not care that your backend is technically healthy. They care that the signup email dumped them into a dead route.
The DMARC specification is dry reading, but the principle is practical: domain identity matters when software sends messages for humans.
Hosting and custom domains
On the hosting side, a platform needs to know which domain should route to which app. This is usually handled through DNS plus a custom domain configuration. It is not identical to an OAuth allowlist, but it must line up with it.
If your app lives at app.example.com, your host, auth provider, email templates, CORS rules, and environment variables should agree. If every tool has a different idea of the production domain, debugging becomes a meeting with five tabs and no owner.
A production checklist before launch
Before you launch a new domain, walk through the whole path.
- Pick the canonical public URL. Decide whether users should land on
example.com,www.example.com, orapp.example.com. - Configure DNS for that domain and verify it resolves to the deployed app.
- Add the domain in your hosting platform.
- Confirm TLS is issued and the browser shows a valid certificate.
- Add required auth callback URLs and authorized domains in your identity provider.
- Update email templates so verification and reset links use the final production URL.
- Set environment variables such as
PUBLIC_APP_URL,APP_URL,AUTH_CALLBACK_URL, or framework equivalents. - Test signup, login, logout, email verification, password reset, and invite acceptance from a fresh browser session.
- Remove old staging or temporary domains from trusted lists.
- Document which service owns each domain setting.
On RunxBuild, keep the hosting side of this in the same operational loop as your custom domain configuration, service deployment, and environment variables. If you are estimating a real launch footprint, the RunxBuild hosting calculator is useful because domains rarely launch alone. They arrive with an app, an API, storage, and usually a database that has opinions about uptime.
Common mistakes that break sign-in
The error message usually says something polite like “domain not authorized.” The root cause is often less polite.
You added the apex domain but not www
If users can reach both example.com and www.example.com, both must be accounted for. Better yet, pick one canonical host and redirect the other. Two public hosts that behave differently is a bug wearing a DNS costume.
You trusted the app domain but forgot the callback URL
Some systems ask for a domain. Others ask for the full redirect URI. app.example.com and https://app.example.com/auth/callback are not the same setting. Read the label carefully before blaming the provider.
Your email templates still point to staging
This one hurts because everything looks fine until a user clicks a real email. Keep email link generation tied to an environment variable and set that variable per environment. Do not hardcode a launch domain into a template and promise to remember it later.
Your frontend and backend disagree
The frontend thinks production is www.example.com. The backend thinks production is app.example.com. The auth provider expects api.example.com. Everyone is technically configured. Nobody is correct.
Use one source of truth for public URLs and keep it in the deployment environment. RunxBuild’s static build and environment configuration docs are a good place to sanity-check how build-time and runtime values are handled.
You left old domains authorized forever
Temporary domains are useful during development. They should not become permanent trust relationships. Review authorized domains after launch, after migrations, and after any domain change. Old domains are quiet risk.
How to handle preview and staging URLs
Preview URLs are helpful. They are also dangerous if you treat them like production.
A preview deployment should not automatically get access to production OAuth clients, production email sender settings, or production secrets. If you need auth in preview, create a separate app/client configuration with preview-safe callback URLs and limited test data.
For staging, use a stable domain such as staging.example.com, not a rotating random URL that has to be re-added every week. Keep staging connected to staging data. Keep production credentials out of it. That sentence is boring because it is correct.
A practical setup:
- production app:
app.example.com - staging app:
staging.example.com - local app:
http://localhost:3000 - separate OAuth client for each environment
- separate environment variables for public URLs and secrets
If an auth provider supports separate projects or clients, use them. It is cleaner than trying to make one giant allowlist serve every environment forever.
Where RunxBuild fits in the workflow
Authorized domains are not just an auth-provider task. They sit across deployment, DNS, TLS, environment variables, and the app runtime.
A good platform should make the hosting side obvious: which domain points at which service, whether TLS is ready, which environment variables are set, and where the live route is. That is the part RunxBuild is built to simplify. You deploy the app, add the domain, connect the backend pieces, and keep the deploy logs close when something fails.
The goal is not to make domain security feel fancy. The goal is to make it boring enough that launch day is about users, not callback URLs.
FAQ
What are authorized domains?
Authorized domains are domains that a service is allowed to trust for redirects, authentication, email links, or domain-sensitive actions. They are usually configured in auth providers, email platforms, hosting tools, or admin consoles that need to know which domains belong to your app.
Why does my app say this domain is not authorized?
The domain or full callback URL you are using is not on the trusted list for the service handling the request. Check the exact host, protocol, path, and environment. https://app.example.com/auth/callback is different from https://example.com/auth/callback.
Do I need to authorize both www and non-www domains?
Only if users can actually use both. The better production pattern is to choose one canonical domain and redirect the other. If both hosts can start an auth or email flow, both must be configured correctly.
Should staging domains be authorized?
Yes, if staging needs to test real login or email flows. Use a separate OAuth client or app configuration for staging when possible, and do not give staging production secrets or production user data.
Are authorized domains the same as CORS?
No. Authorized domains decide which domains a service trusts for auth, redirects, email links, or ownership-sensitive actions. CORS controls which browser origins can read responses from your API. They often involve similar hostnames, but they solve different problems.
Can I use wildcard authorized domains?
Use wildcards only when the provider supports them and you have a real operational reason. Wildcards make setup easier, but they expand the trust boundary. Most production apps are safer with a short explicit list.