Integration
Allowed Origins
A publishable key is public by design, so it is not the key that keeps other people from using your agent. The list of origins allowed on its installation does. It is the one setting worth getting exactly right.
Why this exists
Anyone who views the source of your page can read your publishable key. That is expected. What stops them putting it on their own site is the origin check. A request made with a publishable key must come from a browser origin you have registered on its installation.
- An installation with an empty list answers nowhere. That is the safe default, not a misconfiguration.
- A secret key is never origin checked, which is precisely why it must stay on your server.
- Changes take effect immediately. There is nothing to redeploy after adding or removing an origin.
Manage the list per installation on the API Keys(sign in required) page.
What counts as a match
An origin is the scheme, the host and, when it is not the default, the port. It is not a URL, and it is compared exactly, ignoring letter case. Nothing else about the address is considered.
| You registered | Request from | Result |
|---|---|---|
https://yoursite.com | https://yoursite.com | Allowed |
https://yoursite.com/ | https://yoursite.com | Allowed. The trailing slash is normalized away when the entry is saved |
https://yoursite.com | https://www.yoursite.com | Refused. A subdomain is a different origin |
https://yoursite.com | http://yoursite.com | Refused. A different scheme is a different origin |
https://yoursite.com | https://yoursite.com/pricing | Allowed. The path is not part of the origin |
http://localhost:3000 | http://localhost:5173 | Refused. A different port is a different origin |
Wildcards are not supported. There is no *.yoursite.com. If you serve the widget from several subdomains, add each one, and add both the bare domain and the www form if visitors can reach either.
Writing the entries
Register the origin only, with no path. A trailing slash is normalized away: entering https://yoursite.com/ stores and matches https://yoursite.com.
https://yoursite.com
https://www.yoursite.com
https://app.yoursite.com
http://localhost:3000yoursite.com (no scheme)
http://yoursite.com (http is only accepted for localhost)
https://yoursite.com/chat (a path, not an origin)
*.yoursite.com (wildcards are not supported)Local development needs its own entry, because localhostwith a port is a distinct origin. Add the exact address your dev server prints. You can also test the agent's answers inside the dashboard, using the Playground.
Diagnosing a refusal
Every refused request answers with the same 403 access_denied, whatever the cause, so that a scraped key cannot be confirmed by probing. The response will not identify which possible reason applied.
Compare the browser's exact Origin header with the Allowed Origin configured for the publishable key. The scheme, hostname, and port must all match.
| Symptom | Most likely cause |
|---|---|
| The bubble appears, every question is refused | The site origin is not on the list, or differs by scheme, subdomain or port |
| Works on production, refused on staging | Only the production origin was registered |
| Works in the dashboard, refused on your site | The dashboard is allowed for testing; your own origin still has to be added |
| Refused from a server or from curl | A publishable key requires a browser origin. Use a secret key for server-side calls |
| Suddenly refused everywhere | The key was rotated or revoked, or the agent was deactivated |
| Refusals become 429 | Repeated failed attempts from the same network exhausted the failure budget. Fix the cause, then wait for the window to pass |
Maintaining the list
- Register only origins you control. Every entry is a site that may spend your monthly requests.
- Remove staging origins when a project ends.
- Rotate the publishable key if it appears somewhere unexpected. Rotation replaces only that key and keeps the installation and its origins, so update your snippet and nothing else.
- Prefer one agent per audience over one agent allowed on many unrelated sites, so usage and material stay separable.
Key handling and regeneration are covered on API Keys.
Origins per installation
| Plan | Allowed origins per installation |
|---|---|
| Starter | 1 |
| Lite | 3 |
| Pro | 10 |
| Business | 50 |
| Enterprise | By contract |
Each installation has its own list. A different installation for the same agent can authorize a different site. An empty list authorizes no third-party origin; adding an agent does not add an origin automatically.
Add every origin visitors can actually reach, which usually means the bare domain, the www form, and your local development address. One missing entry looks exactly like a broken integration.
A publishable key is visible in your page source by design, and that is safe only because of this list. Treat the list as the security control it is, and keep entries you no longer serve out of it.