Skip to main content

Allowlist Settings

The Allowlist Settings section allows you to configure domain and URL authorization for enhanced security. Web3Auth requires explicit allowlisting 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 allowlisting is a critical security feature that prevents unauthorized applications from using your Web3Auth project credentials. Only domains and URLs explicitly added to your allowlist 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 allowlisting​

Supported URL formats​

Embedded Wallets supports various URL formats for comprehensive domain coverage:

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

Adding web domains​

  1. Navigate to Project Settings → Allowlist.
  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 allowlisting​

Bundle identifiers​

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

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

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

yourapp://auth
com.yourcompany.yourapp://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:

  • Allowlist 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 allowlisted before the SDK can be used in production. This is a mandatory security requirement.

Production Checklist:

  • ✅ All production domains allowlisted
  • ✅ 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:

https://*.myapp.com

Covers: https://api.myapp.com, https://admin.myapp.com, https://user.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 allowlist
  • 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 allowlist
  • 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 allowlisted
  • Test with both debug and release builds

Security best practices​

Regular audits​

  • Monthly reviews: Check allowlist 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 allowlist 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 allowlisted domains comply with privacy laws
  • Security standards: Meet industry requirements for domain authorization
  • Audit trails: Maintain records of domain modifications

Advanced configuration​

For applications using CDNs or load balancers:

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

Next steps​

On this page