How domains work at Alpheris
Alpheris keeps a list of verified domains per shop. During onboarding, your shop domain is automatically registered as the primary domain. An install key is then generated for exactly this domain — the key that appears in your widget snippet.
On every request from the browser, the server checks two things: whether the origin of the page (i.e. the host on which the widget is embedded) belongs to an allowed domain, and whether the install key sent along matches this shop. If something doesn't match, the server responds with 403 blocked and the widget stays silent.
Origin or Referer. If someone copies your snippet onto a foreign site, the request is rejected — the key is worthless outside your domain.Add & verify a domain
How a domain is verified depends on how you install Alpheris. In all cases you end up with a verified domain plus a matching install key — you don't need to set DNS records or upload files.
For Shopify and WordPress, verification happens implicitly via the confirmed connection: the domains are stored as verified with the verification method shopify or wordpress. For Shopify, the www. variant is also added automatically.
With the code method (embedding the snippet manually), you enter the domain in the dashboard. It's registered as verified with the manual method and an install key is generated for it. There is no separate DNS TXT or file token step with the code method.
Enter a domain in the dashboard
shop.de or www.shop.de. A full URL like https://shop.de/ is also accepted — scheme, path and port are removed automatically.Allowed domains & matching
A request is considered allowed if its host matches a registered domain. Matching recognizes three cases:
| Entry | Allowed |
|---|---|
shop.de | Exactly shop.de — and additionally www.shop.de |
www.shop.de | Exactly www.shop.de |
*.shop.de | shop.de as well as all subdomains, e.g. de.shop.de, checkout.shop.de |
A bare domain (without www.) automatically also covers the www. variant. If you want the widget to run on arbitrary subdomains, add a wildcard entry *.shop.de. For local testing, enter localhost as its own domain — there is no implicit whitelist for it.
Origin, not the IP of the proxy.Multiple domains & plan limits
How many domains you may register and whether you can manage them yourself depends on your plan:
| Plan | Domains | Management |
|---|---|---|
| Free | 1 | Support only |
| Basic | 1 | Support only |
| Business | up to 5 | Self-service, incl. up to 3 changes of the primary domain |
| Enterprise | unlimited | Self-service, no limit |
Your own Alpheris address (yourshop.alpheris.com) doesn't count against your domain limit. It comes with Enterprise and isn't created automatically: you create it in the dashboard under Domains. More under Plans & Billing.
Install key per domain
The install key (attribute data-alpheris-key) uniquely links your snippet to your shop and the domain it was issued for. Here's what the finished snippet looks like:
<!-- Alpheris Chat Widget -->
<script src="https://alpheris.com/widget.js" data-alpheris-key="INSTALL_ID" crossorigin="anonymous" async></script>
<!-- End Alpheris Chat Widget -->Replace INSTALL_ID with the value from your dashboard — there you get the complete snippet already filled in with your real key, ready to copy. The full embedding procedure is under Widget Code.
Properties of the install key
- Issued per domain: When the (primary) domain is verified, the corresponding install key is generated and internally coupled to exactly this domain.
- Revocable: A key can be marked as
revoked; after that, requests with this key are no longer accepted. - Multiple keys possible: More than one key can exist per domain — relevant, for example, after a change of the primary domain. Always use the current snippet from the dashboard.
invalid_install_id. In that case, grab the matching key for the new domain from the dashboard.Strict domain mode (widget domain binding)
Alpheris runs the widget in strict domain mode by default (internally WIDGET_STRICT_DOMAIN, enabled platform-side). In this mode, the following applies to every widget and chat request:
- The
Origin/Refererhost must match an allowed domain of your shop — otherwise403 domain_not_allowed. - If the origin is missing entirely (e.g. a raw direct call without browser context), the request is rejected (
no_origin), unless it demonstrably comes from a logged-in Console/preview session of your shop. - If an install key is provided, it must be valid and belong to the shop.
An optional host fallback via a query parameter is deliberately disabled in strict mode — the host is derived only from the real browser headers, not from freely chosen parameters.
403 blocked with domain_not_allowed or invalid_install_id: the domain isn't (correctly) registered or the key doesn't match the domain. See Troubleshooting.Frequently asked questions
I changed my domain — what do I do?
Enter the new domain in the dashboard and set it as the primary domain. A new install key is generated in the process. Then swap the snippet on your website for the current version from the dashboard. On the Business plan, up to 3 such primary changes are possible; on the Enterprise plan, unlimited.
Does the widget work on staging or test domains?
Yes — add the staging domain as an additional allowed domain (on the Business/Enterprise plan). For local testing, enter localhost.
Do I need a separate entry for every subdomain?
No. A wildcard entry *.shop.de covers the domain and all its subdomains. For www., the bare domain is also enough.