Domain allowlist

The domain allowlist prevents unauthorized sites from embedding your widget or calling widget API endpoints on your behalf.

How it works

When the widget loads, the browser sends an Origin header (or Referer) with requests to:

GET /api/v1/widget/config
POST /api/v1/widget/messages

Chatevo compares the origin against your deployment’s allowed domain list. Non-matching origins receive 403 Forbidden and the widget does not render.

Configure allowed domains

Open Deployments → Web widget → Security → Allowed domains.
Add each origin that should embed the widget.
Save and test from each domain.

Entry format	Matches
`https://www.example.com`	Exact origin
`https://*.example.com`	Any subdomain of `example.com`
`http://localhost:3000`	Local dev (use only in staging deployments)

Include the scheme (https://). Paths are not part of the allowlist — only host/origin.

Common mistakes

Mistake	Symptom	Fix
`www` vs apex mismatch	Widget works on one hostname only	Add both `https://example.com` and `https://www.example.com`
Staging domain missing	403 on preview deploys	Add staging origin or use separate deployment
`http` in production	Blocked or insecure	Use `https://` entries only in production
CDN preview URLs	Random subdomain blocked	Add pattern or dedicated preview deployment

API behavior

# Allowed — Origin matches allowlist
curl -H "Origin: https://www.example.com" \
  "https://api.chatevo.ai/api/v1/widget/config?deployment_id=dep_abc123"

# Blocked — returns 403
curl -H "Origin: https://evil.example.net" \
  "https://api.chatevo.ai/api/v1/widget/config?deployment_id=dep_abc123"

Relationship to CORS

The allowlist enforces the same policy as CORS preflight on widget endpoints. Direct API deployments use API key auth and do not use the domain allowlist.

Troubleshooting

See Domain not allowed for step-by-step debugging.