Both the accessibility widget and the sign-language widget identify themselves with one widget key. The key is public, so Natiq lets you restrict it to your own domains and replace it if it is copied elsewhere.
The widget key
You find the key inside the snippet's data-token attribute, on the widget's Share tab under Install & domains. At load, the widget sends the key to GET /api/v1/a11y-widget/public-config/{key} and receives your published design. That endpoint needs no token and is meant to be called from any visitor's browser.
Because the key sits in your page source, treat it as an identifier, not a secret. Two controls protect it:
- the allowed domains list, which limits where the key works;
- Rotate key, which makes a copied key useless.
Allowed domains
Allowed domains is a list of the sites a widget may run on.
- Empty list: the widget works on any site that has the key.
- One or more entries: every other site is blocked.
Entries are host names only, with no https://, port, path or @:
| Entry | Matches |
|---|---|
www.example.com | exactly that host |
example.com | exactly that host |
*.example.com | example.com and any subdomain of it, at any depth |
Matching is case-insensitive. Only a single *. at the start is allowed; IP addresses are not accepted, and the dashboard checks each entry when you add it, turns a pasted URL into its host name, and rejects invalid entries (up to 50 per list). List both example.com and www.example.com, or use *.example.com to cover both.
Changes take effect when you Publish; the list is part of the published document.
How Natiq decides which site is asking
The backend reads the request's Origin header and falls back to Referer, and uses only the host. Browsers set these honestly, which is what blocks another site embedding your key. A request with neither (for example curl, or a page that strips the referrer) matches nothing once a list exists.
A misuse control, not a lock
The list stops someone else's website from using your widget. It is not authentication: the key is public and a non-browser client can send any Origin. Anyone can read your published design with the key. Do not put anything confidential in a widget's configuration.
What a 404 means
For the public-config call, all of these answer the same 404 (code A11Y_WIDGET_CONFIG_NOT_FOUND), so the response never reveals which keys exist:
- the key is unknown or was replaced (rotated);
- the widget is disabled in the dashboard;
- the widget has never been published;
- the site is not on the allowed-domains list.
A 404 is the one answer that is treated as definitive. The widget responds by removing itself from the page and clearing its cached copy of your design. The accessibility widget also undoes any changes it made to the page.
Everything else fails open: if the request is slow (it gives up after 3 seconds), blocked, returns another error or cannot be parsed, the widget keeps running on the defaults and your page's own attributes. A visitor's page is never made worse by our outage.
If the widget disappeared
| Check | Fix |
|---|---|
| Was the key rotated? | Copy the current snippet from Share and update every page. |
| Is the widget disabled? | Re-enable it in the dashboard. The snippet stays inactive while it is disabled. |
| Was it ever published? | Publish it. |
Is this host on the allowed list (including www)? | Add it, or use a *. entry, and publish again. |
Are you testing from file:// or a sandboxed frame? | Browsers send Origin: null. Natiq then falls back to the Referer; a file:// page sends none, so nothing matches once a list exists. Test from a real host. |
Caching: how long changes take
The published document is cacheable. Responses are fresh for 5 minutes and may be served for up to 10 more while revalidating. Rotating a key, disabling a widget or changing the allowed domains can therefore take up to about 15 minutes to reach every visitor. The widget also keeps its own copy for up to 24 hours, but it drops that copy on a 404.
The public-config endpoint is rate limited per address and per key. A misbehaving embed that reloads the config in a loop may see 429.
Rotate the key
If the key is copied to a site you do not control, list your domains first (that blocks the copy at once for new requests, within the caching window) and then rotate.
Open the widget's Share tab.
Select Rotate key and confirm. The old key keeps working only until caches expire.
Copy the updated snippet and paste it everywhere the widget is installed.
Rotation replaces the key for both the accessibility and the sign-language snippets, so update both tags. Over the API this is POST /api/v1/a11y-widget/{configId}/rotate-key, which needs a signed-in user (Authentication); the response carries the widget's new key.
Web Chat keys
Web Chat uses a different key (data-widgetkey) managed on the agent's Share tab. We found no allowed-domains setting for it. See Install Web Chat.