Skip to main content

Whitelist Settings

The Whitelist Settings section allows you to configure domain and URL authorization for enhanced security. Web3Auth requires explicit whitelisting of domains and URLs that are authorized to use your project's Web3Auth SDK, providing protection against unauthorized usage and potential security threats.

Project Settings Domains

Domain Authorization Overview​

Domain whitelisting is a critical security feature that prevents unauthorized applications from using your Web3Auth project credentials. Only domains and URLs explicitly added to your whitelist can successfully authenticate users through your Web3Auth configuration.

Security Benefits​

  • Prevents Credential Theft: Unauthorized sites cannot use your Client ID
  • Protects User Data: Ensures authentication flows only occur on approved domains
  • Compliance Ready: Meets security standards for production applications
  • Fraud Prevention: Blocks malicious sites from impersonating your application

Web Application Whitelisting​

Supported URL Formats​

Web3Auth supports various URL formats for comprehensive domain coverage:

Standard Domains:

https://myapp.com
https://www.myapp.com
https://app.mycompany.com

Development Environments:

http://localhost:3000
http://localhost:8080
https://dev.myapp.com
https://staging.myapp.com

Subdomain Patterns:

https://*.myapp.com (covers all subdomains)
https://feature-*.myapp.com (wildcard patterns)

Port-Specific URLs:

https://myapp.com:8443
http://localhost:3000
http://127.0.0.1:8080

Adding Web Domains​

  1. Navigate to Project Settings → Whitelist
  2. Click "Add Domain" or similar button
  3. Enter the complete URL including protocol (http:// or https://)
  4. Verify the domain if required
  5. Save the configuration

Best Practices:

  • Always use HTTPS for production domains
  • Include all necessary subdomains
  • Add development and staging environments
  • Test authentication after adding domains

Mobile Application Whitelisting​

Bundle Identifiers​

For mobile applications, whitelist the app's bundle identifier or package name:

iOS Bundle IDs:

com.yourcompany.yourapp
com.yourcompany.yourapp.staging

Android Package Names:

com.yourcompany.yourapp
com.yourcompany.yourapp.debug

Mobile applications using deep links should whitelist their custom URL schemes:

Custom Schemes:

yourapp://auth
com.yourcompany.yourapp://callback

Universal Links (iOS):

https://yourapp.com/auth/callback

App Links (Android):

https://yourapp.com/auth/callback

Environment-Specific Configuration​

Development Environment​

For development and testing:

http://localhost:3000
http://localhost:8080
http://127.0.0.1:3000
https://dev.yourapp.com
https://staging.yourapp.com

Development Tips:

  • Whitelist common development ports
  • Include both localhost and 127.0.0.1
  • Add staging and testing environments
  • Use HTTP for local development (HTTPS for staging)

Production Environment​

Production Requirements

For Sapphire Mainnet projects, at least one domain must be whitelisted before the SDK can be used in production. This is a mandatory security requirement.

Production Checklist:

  • ✅ All production domains whitelisted
  • ✅ HTTPS enforced for all domains
  • ✅ Subdomain coverage complete
  • ✅ Mobile bundle IDs added
  • ✅ Deep link schemes configured
  • ✅ Remove development URLs

Wildcard Domains​

Subdomain Wildcards​

Use wildcard patterns to cover multiple subdomains efficiently:

Single-level wildcard:

https://*.myapp.com

Covers: https://api.myapp.com, https://admin.myapp.com, https://user.myapp.com

Multi-level wildcards:

https://*.*.myapp.com

Covers: https://api.v1.myapp.com, https://admin.staging.myapp.com

Dynamic Subdomains​

For applications with dynamic subdomains (multi-tenant apps):

https://*.myapp.com
https://tenant-*.myapp.com
https://*.saas.myapp.com

Verification Process​

Domain Verification​

Some domains may require verification to ensure ownership:

  1. DNS Verification: Add a TXT record to your domain's DNS
  2. File Upload: Upload a verification file to your web server
  3. HTML Meta Tag: Add a meta tag to your website's homepage

Verification Status​

Monitor the verification status in your dashboard:

  • ✅ Verified: Domain is confirmed and active
  • ⏳ Pending: Verification in progress
  • ❌ Failed: Verification unsuccessful, requires attention

Common Issues and Solutions​

Authentication Failures​

Problem: Users cannot authenticate on your domain Solutions:

  • Verify the domain is in your whitelist
  • Check for typos in the domain name
  • Ensure protocol (http/https) matches exactly
  • Confirm subdomain patterns are correct

Development Environment Issues​

Problem: Local development not working Solutions:

  • Add http://localhost:PORT to whitelist
  • Include http://127.0.0.1:PORT as alternative
  • Check if your development server uses a different port
  • Verify protocol matches (http vs https)

Mobile App Issues​

Problem: Mobile authentication failing Solutions:

  • Verify bundle ID matches exactly
  • Check deep link scheme configuration
  • Ensure URL schemes are properly whitelisted
  • Test with both debug and release builds

Security Best Practices​

Regular Audits​

  • Monthly Reviews: Check whitelist for unused domains
  • Remove Stale Entries: Delete old development or staging URLs
  • Monitor Access: Review authentication patterns for anomalies
  • Update Documentation: Keep domain lists current for your team

Principle of Least Privilege​

  • Minimal Domains: Only whitelist necessary domains
  • Specific Patterns: Avoid overly broad wildcard patterns
  • Environment Separation: Use different projects for dev/staging/prod
  • Regular Cleanup: Remove domains when no longer needed

Compliance Considerations​

  • Data Residency: Consider where authentication occurs
  • Privacy Regulations: Ensure whitelisted domains comply with privacy laws
  • Security Standards: Meet industry requirements for domain authorization
  • Audit Trails: Maintain records of domain modifications

Advanced Configuration​

CDN and Load Balancer Support​

For applications using CDNs or load balancers:

https://cdn.myapp.com
https://lb.myapp.com
https://edge-*.myapp.com

Multi-Region Deployments​

For global applications with regional domains:

https://us.myapp.com
https://eu.myapp.com
https://asia.myapp.com
https://*.global.myapp.com

API Gateway Integration​

For applications behind API gateways:

https://api.myapp.com
https://gateway.myapp.com
https://*.api.myapp.com

Next Steps​

On this page