ProjectSecurityWhitelist URL

Whitelist Origin URLs

URL whitelisting restricts which domains can use your UTXOS SDK integration. Requests from non-whitelisted origins are rejected, preventing unauthorized applications from using your project credentials.

Why should you whitelist URLs?

Without URL restrictions, anyone who obtains your project ID could:

  • Use your SDK quota on their own site
  • Trigger API calls billed to your account
  • Associate their application with your project

Whitelisting ensures only your approved domains can interact with your project.

⚠️

URL whitelisting applies to client-side SDK usage only. Server-side API calls authenticate with your API key, which provides separate security.

Configure Whitelist

Open project settings

Go to Dashboard > Project Settings.

Add allowed origins

Enter each allowed origin URL in the Whitelist Origin URL section.

Save changes

Click Save to apply the whitelist immediately.

URL Format

Enter origin URLs in standard format:

https://example.com
https://app.example.com
http://localhost:3000
ComponentRequiredExample
ProtocolYeshttps:// or http://
DomainYesexample.com
SubdomainOptionalapp.example.com
PortIf non-standard:3000
PathNo (ignored)Do not include paths

Do not include paths in whitelist URLs. The whitelist matches the origin only, which consists of protocol, domain, and port.

Common Configurations

Production Only

https://myapp.com
https://www.myapp.com

Production + Staging

https://myapp.com
https://www.myapp.com
https://staging.myapp.com

Production + Local Development

https://myapp.com
https://www.myapp.com
http://localhost:3000
http://localhost:3001

Multiple Subdomains

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

Wildcard Support

⚠️

Wildcard subdomains are not currently supported. You must list each subdomain explicitly.

If you need to support many subdomains, list each one individually:

https://tenant1.myapp.com
https://tenant2.myapp.com
https://tenant3.myapp.com

For dynamic multi-tenant applications with many subdomains, contact support@utxos.dev to discuss your use case.

Local Development

For local development, add your development URLs:

http://localhost:3000
http://localhost:3001
http://127.0.0.1:3000

Remember to use http:// for localhost, not https://, unless you have configured local SSL.

Development vs Production Projects

For better security, consider using separate UTXOS projects:

ProjectWhitelist
Developmenthttp://localhost:3000
Productionhttps://myapp.com, https://www.myapp.com

This prevents accidentally using production credentials in development.

Testing Your Whitelist

Verify Allowed Domain

  1. Open your application on a whitelisted domain
  2. Initialize the SDK and make a request
  3. The request should succeed

Verify Blocked Domain

  1. Open browser developer tools on a non-whitelisted domain
  2. Attempt to use your SDK or project ID
  3. You should see an error indicating the origin is not allowed

Test with curl (Server-Side)

Whitelist only affects browser requests. Server-side requests with your API key work regardless of whitelist settings:

curl -X POST https://api.utxos.dev/v1/... \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Error Messages

When a request comes from a non-whitelisted origin:

Error: Origin not allowed. Add https://unauthorized-domain.com to your project whitelist.

Users on non-whitelisted domains see this error, preventing any SDK functionality.

Troubleshooting

”Origin not allowed” on production

Cause: Production domain not in whitelist.

Solution: Add your production domain with the correct protocol (https://) to the whitelist.

”Origin not allowed” on localhost

Cause: Localhost not in whitelist, or wrong port/protocol.

Solution:

  1. Add http://localhost:3000 (or your port)
  2. Verify you are using http:// not https://
  3. Check the exact port number

Whitelist updated but still blocked

Cause: Browser cache or propagation delay.

Solution:

  1. Wait 1-2 minutes for changes to propagate
  2. Clear browser cache and reload
  3. Try in an incognito window

Works locally, fails in production

Cause: Different domains or protocols.

Solution:

  1. Verify production URL is in whitelist
  2. Check for www vs non-www differences
  3. Ensure https:// is used (not http://)

Mobile app not working

Cause: Mobile apps may use different origin handling.

Solution:

  1. For React Native or similar, the origin may be null or a custom scheme
  2. Contact support@utxos.dev for mobile-specific configuration

Security Recommendations

  1. List only necessary domains - Do not add domains “just in case”
  2. Remove localhost in production - Use separate projects for development
  3. Use HTTPS in production - Never whitelist http:// for production domains
  4. Review whitelist regularly - Remove domains you no longer use
  5. Combine with API keys - Whitelist protects client-side; API keys protect server-side

Next Steps

PricingEntity Secret