> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streambird.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Domain Whitelisting

> Configure and manage whitelisted domains for secure authentication flows in MoonKey

## 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](https://dashboard.moonkey.fun), 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`

<Info>
  MoonKey validates the domain only—all paths under that domain are automatically allowed.
</Info>

### 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`

<Warning>
  Subdomains are not automatically included. Make sure to whitelist each subdomain your application uses.
</Warning>

## 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](https://dashboard.moonkey.fun)
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**

<Tip>
  Add separate domains for development, staging, and production environments to test authentication flows across your deployment pipeline. Remember to whitelist each subdomain separately.
</Tip>

## 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 Case                        | Whitelisted Domain            |
| ------------------------------- | ----------------------------- |
| Production app                  | `https://app.example.com`     |
| Marketing site                  | `https://example.com`         |
| Staging environment             | `https://staging.example.com` |
| Local development               | `http://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](https://dashboard.moonkey.fun)
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