API Keys & Security
J.O.S.I.E uses API keys to authenticate widget and server requests per tenant.
Key types
| Prefix | Purpose | Where used |
|---|---|---|
wk_live_... | Widget key | data-josie-key, public embed |
wk_demo_... | Demo / preview | Platform demo chat only |
sk_live_... | Server key | Backend integrations (if enabled) |
Widget keys are designed for browser embed — protection comes from origin allowlisting and rate limits, not secrecy alone. Still treat keys as credentials and rotate if leaked.
Creating and revoking
Dashboard → API Keys
- Create — full key shown once; copy immediately
- Revoke — instant; widget stops working until you deploy a new key
- Prefix display — dashboard shows
wk_live_abcd...for identification
Limits: Basic 1 active key, Pro 5, Enterprise unlimited.
Domain allowlisting
Every widget request includes an Origin header. J.O.S.I.E rejects requests from unlisted origins even with a valid key.
Configure under Configure → Allowed origins.
Tenant isolation
- Database rows scoped by
tenantId - Documents in isolated storage paths
- API keys hashed with bcrypt
- Avatars and config cached with
Vary: Cookie— no cross-tenant cache leaks - Chat logs and RAG chunks never shared across tenants
Message quotas
Each message (user + assistant turn) counts toward your monthly limit. Limits reset on billing cycle.
| Tier | Messages/month |
|---|---|
| Free | 50 |
| Basic | 400 |
| Pro | 10,000 |
| Enterprise | Unlimited |
When exceeded, API returns quota error — widget should show a friendly message.
Data retention
Chat sessions may be retained for analytics and support per your plan and privacy policy. Request data export via support for Enterprise agreements.
Security checklist
- Only HTTPS origins in production
- Revoke keys shared with former vendors
- Don't commit keys to git — use env vars for server keys
- Keep CSP tight on your site
- Review allowed origins after domain migrations