Restrict the domains that can load the agent

An environment's allowed domains are the hosts where the widget can load and chat. With no domains listed, the agent runs on any page that has its ID. Add your domains so that a site that copies your snippet gets nothing and spends none of your model provider's tokens.

Add allowed domains

To restrict an environment to your domains:

In the portal, go to Web Agents and select your agent.
In the agent's header, select the control that lists each environment with the version it serves. The Deployments dialog opens.
Under the environment you want to restrict, enter your domains in Allowed domains, separated by commas or spaces.
Select Apply changes.

The list takes effect when you apply it. It belongs to the environment, so it does not create a version and does not need a publish.

Domain patterns

Pattern	Matches
`example.com`	That exact host, on any port.
`*.example.com`	`example.com` and every subdomain of it.
`localhost:5173`	That host on that port only.

A pattern without a port matches every port. Matching ignores letter case.

A typical setup lists your public domains on Production and localhost with your dev server's port on the environment you develop against.

What a page on another domain gets

Faustine checks the page's domain twice:

When the page loads the widget script. The response is 403, with a comment that names the environment whose list rejected the page.
On every chat request. The response is 403 with the error origin_not_allowed.

A page can hide its address from the first check. It cannot hide it from the second, so a page outside the list never holds a conversation.

Troubleshooting

Symptom	Cause	Fix
The widget does not appear, and the script request returns `403` with `this page's domain is not on the allowlist`	The page's host is not in the list of the environment the widget loads.	Add the host to Allowed domains for that environment.
The widget stopped working on your machine after you added your production domain	A list that is not empty rejects every host that is not in it, including `localhost`.	Add `localhost` with your dev server's port, or load a different environment in development.
`www.example.com` is rejected	The list has `example.com`, which matches that exact host only.	Use `*.example.com`.
A domain is allowed on Production and rejected on Staging	Each environment has its own list.	Add the domain under each environment that should accept it.

Next steps

Identity verification: make sure the agent knows which user it is talking to.
React quickstart: choose which environment the widget loads.

Last updated November 13, 2026