Widget Security
Protect your widget from unauthorized use and control which websites can embed your chat widget using origin whitelisting and security best practices.
What is Widget Security?
Widget security controls which websites are allowed to load and use your chat widget. Without proper security configuration, anyone could copy your widget script and embed it on their own website, using your message credits and potentially confusing visitors with unauthorized implementations.
OpenSpeechAI uses origin whitelisting to prevent unauthorized usage. Only websites you explicitly allow can load your widget and send messages to your agent.
Understanding Allowed Origins
An origin is the domain name where your widget is embedded. When a visitor opens your website and loads the chat widget, their browser sends the origin (the website's domain) along with every message request. OpenSpeechAI checks this origin against your allowed origins list and blocks requests from unauthorized domains.
For example, if your website is example.com and you add it to your allowed origins, only visitors on example.com can use the widget. If someone copies your widget script and puts it on unauthorized-site.com, their messages will be blocked with an origin error.
This protects your message credits, prevents widget theft, and ensures you have full control over where your agent appears.
Adding and Managing Origins
To configure allowed origins, navigate to the Agents page, click on your agent, and go to the Widget tab. Scroll down to the Allowed Origins section.
You'll see an input field where you can add new origins and a list of currently allowed origins below it. To add a new origin, type the domain name (without https:// or www) and click Add. For example, enter example.com, not https://example.com or www.example.com.
The origin will appear as a tag in the list below. To remove an origin, click the X icon next to it. You must have at least one allowed origin at all times - the system won't let you remove the last one to prevent accidentally locking yourself out.
Common origin formats include:
| Origin | Allows |
|---|---|
example.com | Every page on both www.example.com and example.com |
subdomain.example.com | Every page on that specific subdomain |
*.example.com | Every page on all subdomains of example.com, including the root |
* | Every page on every domain (not recommended for production) |
Path-Based Restrictions
You can restrict your widget to specific paths on your domain. This is useful when you want the widget on some pages but not others, like showing it on marketing pages but hiding it from your app dashboard.
To use path-based restrictions, include the full URL with the path. The final / or /* is significant:
| Entry | Allows |
|---|---|
https://example.com/* | Every page on that exact HTTPS origin |
https://example.com/ | Only the homepage |
https://example.com/docs | Only the exact /docs page |
https://example.com/docs/* | /docs and all subpaths like /docs/guides/setup |
https://example.com/pricing | Only the exact /pricing page |
When entering a full URL, use / for only the homepage and /* for the whole origin. Browsers often display https://example.com and https://example.com/ identically, so include /* explicitly when you want every page. For a named path, the /* suffix includes that path and every path beneath it.
Example: Marketing pages only
If you want the widget on your public pages but not your authenticated app routes, add each public path:
https://example.com/
https://example.com/docs/*
https://example.com/pricing
https://example.com/blog/*
https://example.com/aboutWith this setup, the widget appears on your homepage, docs, pricing, blog, and about pages, but NOT on /app/* or any other paths you haven't listed.
Security Best Practices
Common Security Scenarios
Troubleshooting Origin Issues
If your widget isn't loading or messages aren't sending, origin configuration is often the culprit. Here's how to diagnose and fix common issues:
Still having issues? Check your browser console for specific error messages, then contact our support team with the error details and we'll help you resolve it.
Last updated: August 23, 2026