Skip to main content

Domain Whitelist

The domain whitelist is a security feature that ensures Recapt only accepts data from your authorized domains. This prevents unauthorized websites from sending data to your account.

Why Whitelist Domains?​

  • Security: Prevents malicious actors from sending fake session data
  • Data Integrity: Ensures all recorded sessions are from your actual websites
  • Cost Control: Avoids unexpected usage from unauthorized sources

Adding Domains​

During Installation​

  1. Navigate to Installation in your Recapt dashboard
  2. In Step 2 (Domain Settings), enter your domain
  3. Click Add Domain
  4. Repeat for additional domains

In Settings​

  1. Go to Settings > Whitelist Domains
  2. Enter the domain name in the input field
  3. Click Add Domain

Domain Format​

Enter domains without the protocol (http:// or https://):

CorrectIncorrect
example.comhttps://example.com
app.example.comhttp://app.example.com
www.example.comwww.example.com/path

Common Domain Configurations​

Single Domain Website​

If your website runs on one domain:

example.com

With WWW Subdomain​

If users access your site with and without www:

example.com
www.example.com

Multiple Subdomains​

For applications with multiple subdomains:

example.com
app.example.com
dashboard.example.com
admin.example.com

Staging and Production​

For different environments:

example.com
staging.example.com
dev.example.com
tip

You can use the same API key across all your domains, or create separate API keys for different environments.

Wildcard Domains​

Currently, Recapt does not support wildcard domains (e.g., *.example.com). You must add each subdomain individually.

Localhost Development​

By default, localhost is not whitelisted. To enable recording during development:

  1. Go to Settings > Organization
  2. Toggle Localhost to enabled

This allows requests from:

  • localhost
  • 127.0.0.1
  • Any localhost port (e.g., localhost:3000)
warning

We recommend keeping localhost disabled in production. Only enable it during active development to avoid recording unwanted test sessions.

Managing Domains​

Viewing Whitelisted Domains​

  1. Go to Settings > Whitelist Domains
  2. All your whitelisted domains are displayed in the table

Removing a Domain​

  1. Go to Settings > Whitelist Domains
  2. Find the domain you want to remove
  3. Click the trash icon next to the domain
  4. Confirm the removal
caution

Removing a domain immediately stops Recapt from accepting data from that domain. Make sure you've removed the Recapt script from the domain before removing it from the whitelist.

Troubleshooting​

Sessions Not Recording​

If sessions aren't appearing in your dashboard:

  1. Check the domain is whitelisted: Verify the exact domain (including subdomains) is in your whitelist
  2. Check for typos: Ensure the domain is spelled correctly
  3. Check localhost setting: If testing locally, ensure localhost is enabled
  4. Check the browser console: Look for any error messages from Recapt

CORS Errors​

If you see CORS-related errors:

  1. Verify the domain making requests matches a whitelisted domain exactly
  2. Check that you're not including the protocol in the whitelist
  3. Ensure subdomains are added separately

Best Practices​

  1. Add all environments: Include production, staging, and development domains
  2. Be specific: Add exact subdomains rather than relying on the main domain
  3. Regular audits: Periodically review your whitelist and remove unused domains
  4. Test after changes: Verify recording works after modifying the whitelist