Authentication
How dashboard sessions, API keys, public widget endpoints, and public forms authenticate.
Authentication
RogerIQ has four authentication patterns. Use the one that matches the surface you are working with.
| Surface | Authentication | Used by |
|---|---|---|
| Dashboard | Browser session cookie | RogerIQ app users |
| Public API | riq_ API key | Server integrations and automation |
| Widget runtime | Project ID plus visitor token | Customer-facing widget |
| Forms and beacons | Public form or beacon ID plus origin controls | Hosted forms, iframe embeds, HTML POST, JSON submit |
Public API Keys
API keys begin with riq_. Send them through either Authorization: Bearer or X-API-Key.
bashcurl https://api.rogeriq.com/api/v1/projects/prj_123/conversations \ -H "Authorization: Bearer riq_your_key"
bashcurl https://api.rogeriq.com/api/v1/projects/prj_123/conversations \ -H "X-API-Key: riq_your_key"
API keys are scoped to an organization. The project in the request path must belong to that organization.
Scopes
| Scope | Grants |
|---|---|
read | Read conversations, messages, contacts, webhooks, and delivery history. |
write | Create and update conversations, messages, contacts, and webhooks. |
admin | Administrative API access where supported. |
Widget Identity
The widget initializes with a projectId. When a visitor starts or resumes a conversation, RogerIQ issues a visitor token for that conversation. The token is stored locally and used to send follow-up messages.
For verified identity, call identify from your application.
jsRogerIQ("identify", { email: "ada@example.com", name: "Ada Lovelace", plan: "pro"});
If secure mode is enabled, include a server-generated HMAC signature. See Identify and secure mode.
Public Forms
Forms and beacons are intentionally public so customers can submit them without an account. Protection is layered:
- allowed origins on forms and beacons
- per-IP rate limits
- honeypot fields
- FingerprintIQ bot evaluation
- Turnstile on hosted RogerIQ form pages
- file validation before upload to R2
Never put a riq_ API key in browser JavaScript. Use public widget, form, and beacon endpoints for browser surfaces. Use API keys only from trusted server code.