Public Embed Keys
Safely support one-script chatbot embeds without exposing broad API credentials.
A website chatbot needs a credential that can be used from the browser. That credential should be publishable, scoped, and limited. It should not be the same as a server-side secret API key.
Credential Types
| Key type | Exposed to browser? | Scope |
|---|---|---|
| Secret API key | No | Backend API calls for trusted servers. |
| Public embed key | Yes | One published chatbot, on allowed domains, with strict limits. |
Recommended Flow
Widget loads with a public embed key
-> Fluo validates origin, key, agent, and limits
-> Fluo creates a short-lived chat session
-> The browser sends chat messages using that session
This keeps the embed simple while making the exposed key low-risk.
Abuse Controls
Public embed keys should be protected by several controls at once:
| Control | Why it matters |
|---|---|
| Allowed origins | Prevents casual reuse of the key on unrelated websites. |
| Agent scope | Limits the key to one chatbot or explicit agent allowlist. |
| Endpoint scope | Prevents the key from managing projects, agents, knowledge, integrations, or billing. |
| Rate limits | Reduces automated abuse by key, IP, origin, and session. |
| Spend caps | Stops unexpected model or tool costs. |
| Short-lived sessions | Lets Fluo expire browser sessions without rotating the public key. |
| Optional bot checks | Adds friction for suspicious or anonymous traffic. |
What Public Keys Should Not Do
Public embed keys should not be able to:
- Create, update, or delete agents.
- Manage integrations or credentials.
- Read project settings.
- List API keys.
- Access usage or wallet information.
- Trigger write-capable tools unless explicitly allowed.
Allowed Domains
Add every production domain where the widget runs:
https://example.comhttps://www.example.comhttps://app.example.com
Use development origins only for local testing, and remove them from production keys.
Budget Defaults
Good starting limits for public embeds:
| Limit | Starting point |
|---|---|
| Messages per minute per IP | 20 |
| Active streams per session | 1 |
| Daily messages per key | Based on expected site traffic |
| Monthly spend cap | Set below the customer's approved budget |
| File size | Keep small unless the use case requires large documents |
Incident Response
If an embed key is abused:
- Disable or rotate the key.
- Review top origins, IPs, and sessions.
- Tighten allowed domains and rate limits.
- Check whether write-capable tools were enabled.
- Create a new key after limits are updated.