Skip to main content

Origin Whitelisting (CORS)

Origin whitelisting — labelled URL White Listing (CORS) in the Developer Portal — controls which websites are allowed to host your ChainIT integration. It prevents unauthorized domains from embedding your OAuth flow or making API calls using your clientId.

Whitelisting is enforcement, not configuration

Every IDP and Hosted UI application must register at least one allowed origin. Requests from origins not on the list are rejected with a 401 Unauthorized or a CORS error.

Configuration​

Configure allowed origins in the Developer Portal under URL White Listing (CORS) when creating or editing an application.

https://app.example.com
https://staging.example.com
https://app.example.com
http://localhost:3000

Rules​

RuleExampleSupported?
Full origin (protocol + host + port)https://app.example.com✅
Subdomain wildcard (Hosted UI only)https://*.example.com✅
Localhost with porthttp://localhost:5173✅
Bare * (any origin)*❌ Rejected
Path or trailing slashhttps://app.example.com/path❌ Strip paths

Important notes​

  • Protocol matters: https://app.com and http://app.com are different origins. List both if needed.
  • Port matters: http://localhost:5173 and http://localhost:3000 are different origins.
  • Trailing slashes: Stripped automatically — do not add them.
  • Subdomain wildcards (Hosted UI only): https://*.example.com matches https://app.example.com and https://staging.example.com, but not https://example.com (the bare domain without a subdomain). Wildcards are only honored for Hosted UI applications — IDP applications require exact-origin matches.
  • No paths: Origins are protocol + host + port only. Paths after the origin are ignored.
  • One per line: Enter each origin on its own line in the text area.

Best practices​

1. List every environment​

Add origins for every environment your application runs in:

  • Production: https://app.example.com
  • Staging: https://staging.example.com
  • Development: http://localhost:5173
  • Preview / PR deployments: https://preview-123.example.com

2. Never use a bare *​

Wildcard origins defeat the purpose of whitelisting. The portal rejects * to prevent accidental misconfiguration.

3. Prefer subdomain wildcards for previews (Hosted UI only)​

For Hosted UI applications, if your deployment model uses ephemeral subdomains (https://pr-42.app.example.com), use https://*.app.example.com instead of listing each one individually. IDP applications do not support wildcards — list each preview origin explicitly.

4. Audit regularly​

Review your origin list periodically. Remove stale origins (decommissioned environments, old preview URLs) to reduce attack surface.

5. Match redirect URIs​

For IDP applications, ensure that the redirect_uri parameter in your authorize request resolves to an origin on the whitelist. While redirect URIs and allowed origins are separate validations, mismatches cause opaque failures.

Troubleshooting​

CORS error in the browser console​

If you see a CORS error in the browser's developer console when calling the token or userinfo endpoint:

  1. Confirm the origin (window.location.origin) is listed in URL White Listing (CORS) for your application.
  2. Check for protocol/port mismatches — https:// vs http://, or a different port number.
  3. Verify the entry has no trailing slash or path.

Hosted UI shows "Origin is not allowed"​

The SDK's first browser-side call checked the X-Origin header against your whitelist and the origin was not found.

  1. Open the application in the Developer Portal and verify the origins under URL White Listing (CORS).
  2. Check that the whitelisted origin matches window.location.origin exactly — protocol, host, and port.
  3. If using a staging or local environment, make sure that specific origin was added.
Related pages