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:
example.com - Allows both www.example.com and example.com
subdomain.example.com - Allows only that specific subdomain
*.example.com - Allows all subdomains of example.com (including the root domain)
* - Allows all domains (not recommended for production)
Security Best Practices
Use specific domains in production - Once you're ready to go live, replace * with your actual domain. This prevents unauthorized websites from using your widget and consuming your message credits. If your widget is only on example.com, only allow example.com.
Be careful with wildcards - The * wildcard allows any website to use your widget. This is convenient during initial setup and testing, but it's a security risk in production. Anyone who finds your widget script can embed it on their site and use your credits. Remove * once you know your production domain.
Add all your subdomains - If you use multiple subdomains, you can either add each one individually or use the wildcard pattern *.example.com to allow all subdomains at once. The wildcard approach is convenient if you have many subdomains or frequently add new ones.
Update when changing domains - If you migrate to a new domain or add new subdomains, remember to update your allowed origins. Otherwise, your widget will stop working on the new domain until you add it to the list.
Common Security Scenarios
Single website with one domain - Add just your domain like example.com. This is the most common and secure setup. Your widget works on your site and nowhere else.
Multiple subdomains - If your product spans multiple subdomains (like www.example.com, app.example.com, and blog.example.com), you have two options. You can add each subdomain separately for maximum control, or use the wildcard pattern *.example.com to allow all subdomains with a single entry. The wildcard pattern is especially useful for SaaS applications where customers get their own subdomains, or when you have many staging and development environments.
Testing before launch - If you're still deciding on your domain or testing on multiple staging environments, you can temporarily use * to allow all origins. Just remember to replace it with specific domains before going live to production.
Multi-site deployments - If you run multiple websites and want the same agent on all of them, add each domain to your allowed origins. For example, site1.com, site2.com, and site3.com can all use the same widget.
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:
Widget loads but messages fail - Check your browser's developer console (press F12). If you see an error mentioning "Origin not allowed" or "CORS error", your current domain isn't in the allowed origins list. Add the domain you're visiting to your allowed origins and try again.
Widget works on one domain but not another - Each domain needs its own entry in the allowed origins list. If your widget works on www.example.com but not example.com, add both to your allowed origins.
Widget stops working after domain change - If you recently changed your domain or moved to a new subdomain, update your allowed origins to include the new domain. The old domain will stop working once you remove it from the list.
Multiple environments - If you have staging, development, and production environments, each needs to be in your allowed origins list. Check which environment you're currently on and make sure it's allowed.
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: November 18, 2024