Skip to main content

​
What is domain whitelisting?

When your users authenticate via OAuth providers (like Google, Apple, GitHub) or receive magic links via email, MoonKey needs to ensure they’re redirected to legitimate domains you control. By whitelisting domains in the MoonKey Dashboard, you specify which domains are authorized for authentication flows. Once a domain is whitelisted, MoonKey automatically handles all authentication redirects to that domain—no need to configure specific URLs or paths.

​
How it works

Simply whitelist a domain, and MoonKey takes care of the rest: 
http://localhost:3000
Once whitelisted, all authentication flows (OAuth, magic links, etc.) will be valid for any path on that domain:
  • ✅ https://some-domain.com/login
  • ✅ https://some-domain.com/auth/callback
  • ✅ https://some-domain.com/welcome
  • ✅ https://some-domain.com/some/path
MoonKey validates the domain only—all paths under that domain are automatically allowed.

​
Subdomains

Each subdomain must be whitelisted separately. For example, if you whitelist https://some-domain.com, the subdomain https://welcome.some-domain.com will not be automatically included. To support multiple subdomains, add each one individually:
  • https://some-domain.com
  • https://welcome.some-domain.com
  • https://app.some-domain.com
Subdomains are not automatically included. Make sure to whitelist each subdomain your application uses.

​
Where domain whitelisting is used

Domain whitelisting secures the following authentication methods:
  • OAuth authentication - Google, Apple, GitHub, Discord, Microsoft
  • Magic links - Email-based passwordless authentication
  • Email OTP - One-time passcode authentication flows

​
Configuring whitelisted domains

To whitelist domains for your app:
  1. Log in to the MoonKey Dashboard
  2. Select your app from the dropdown
  3. Navigate to Domain Whitelisting in the sidebar
  4. Click Add Domain
  5. Enter your domain (e.g., https://app.some-domain.com or http://localhost:3000)
  6. Click Save
Add separate domains for development, staging, and production environments to test authentication flows across your deployment pipeline. Remember to whitelist each subdomain separately.

​
Best practices

​
Security

  • Use HTTPS in production - Never use HTTP domains in production environments
  • Whitelist only what you need - Only add domains and subdomains you actively use for authentication
  • Include all subdomains - Remember to whitelist each subdomain separately
  • Regular audits - Review and remove unused domains periodically

​
Development workflow

  • Localhost for development - Add http://localhost:3000 (or your local port) for development
  • Environment-specific domains - Create separate entries for dev, staging, and production
  • Test thoroughly - Verify authentication flows work correctly before going live

​
Domain formats

  • Include protocol - Always specify http:// or https://
  • Port numbers - Include port numbers when necessary (e.g., http://localhost:3000)
  • No paths required - Just specify the domain; MoonKey handles all paths automatically

​
Example whitelisted domains

Here are common domain configurations:
Use CaseWhitelisted Domain
Production apphttps://app.example.com
Marketing sitehttps://example.com
Staging environmenthttps://staging.example.com
Local developmenthttp://localhost:3000
Local development (custom port)http://localhost:8080

​
Troubleshooting

​
Invalid domain error

If you receive an “Invalid domain” error during authentication:
  1. Verify the domain is whitelisted in the MoonKey Dashboard
  2. Check that the protocol matches (http:// vs https://)
  3. Ensure the port number is included if using non-standard ports
  4. If using a subdomain, verify it’s whitelisted separately from the main domain

​
Authentication redirect not working

If users aren’t being redirected after authentication:
  1. Confirm the domain is properly whitelisted
  2. Check that you’re using the correct protocol (HTTPS in production)
  3. For localhost, ensure the port number matches your development server
  4. Check browser console for any redirect or CORS errors
  5. Verify your OAuth callback URLs match the whitelisted domain

​
Subdomain issues

If authentication isn’t working on a subdomain:
  1. Verify the specific subdomain is whitelisted (subdomains are not automatically included)
  2. Check that the subdomain format is correct (e.g., https://app.example.com)
  3. Ensure both the protocol and subdomain match exactly
  4. Add each subdomain separately in the dashboard