IllumiChat supports two authentication methods. Session authentication (Auth0) is used by the app and browser-based requests. Workspace API keys are used for server-to-server access and no-code integrations such as Zapier.
Session Authentication
Session-based authentication is the primary method for browser-based applications. When a user logs in at app.illumichat.com, Auth0 issues a session cookie that is automatically included in subsequent requests.
| Detail | Value |
|---|
| Cookie name | authjs.session-token |
| Set by | Auth0 login flow |
| Scope | app.illumichat.com |
credentials: "include" in your fetch calls:
const response = await fetch("https://app.illumichat.com/api/assistants", {
method: "GET",
credentials: "include",
});
API Key Authentication
Workspace API keys authenticate server-to-server requests to the public v1 REST API and power the Zapier integration. A key acts on behalf of the whole workspace, not an individual user.
API keys use a static bearer token — there is no OAuth2 flow. Auth0 sessions remain the mechanism for browser and in-app requests.
Creating a key
Go to Settings → API Keys in IllumiChat and create a key. Keys begin with the prefix wsk_live_. The full key is shown only once at creation time — copy it somewhere safe. Only workspace owners and admins can create or revoke keys.
Creating and using API keys for write actions requires a Pro plan or higher. Requests from Free workspaces are rejected with 403 plan_upgrade_required.
Making authenticated requests
Send the key as a bearer token:
curl -X GET https://app.illumichat.com/api/v1/contacts \
-H "Authorization: Bearer wsk_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json"
Scopes
Each key carries one or more scopes. A request that needs a scope the key lacks is rejected with 403 missing_scope. Grant only the scopes an integration needs.
| Scope | Grants |
|---|
contacts:write | Create and update CRM contacts |
tickets:write | Create and update support tickets |
chat:write | Send messages into live chat sessions |
events:read | Subscribe to workspace events (webhooks / Zapier triggers) |
Revoking a key
Revoke a key from Settings → API Keys at any time. Revocation is immediate and disconnects every integration — including any Zaps — using that key.
Public Endpoints
The following endpoints do not require authentication:
| Method | Endpoint | Description |
|---|
GET | /api/widget/{assistantId}/config | Retrieve widget configuration |
POST | /api/widget/{assistantId}/session | Create a widget chat session |
POST | /api/widget/{assistantId}/chat | Send a message via the widget |
POST | /api/widget/{assistantId}/lead | Capture a lead from the widget |
POST | /api/widget/{assistantId}/feedback | Submit conversation feedback |
GET | /api/widget/{assistantId}/history | Retrieve widget chat history |
POST | /api/widget/tickets/create | Create a support ticket (rate limited) |
SMS Webhooks
| Method | Endpoint | Description |
|---|
POST | /api/sms/webhook/{assistantId} | Inbound SMS from Twilio |
POST | /api/sms/status/{assistantId} | Twilio delivery status callback |
SMS webhook endpoints validate the Twilio request signature to verify that incoming requests originate from Twilio.
Authorization
After authentication, IllumiChat checks your permissions before processing each request.
Workspace Roles
| Role | Capabilities |
|---|
owner | Full control including billing, workspace deletion |
admin | Manage members, assistants, settings |
member | Use assistants, create and view chats |
guest | Limited read-only access |
Assistant Visibility
| Visibility | Who Can Access |
|---|
public | All workspace members |
workspace | Active workspace members |
private | Creator, admins, and explicitly granted users |
Auth Error Responses
| Status | Meaning | What to Do |
|---|
401 | Unauthorized — missing or expired session | Redirect the user to login |
403 | Forbidden — authenticated but lacks permission | Check the user’s workspace role |
Session tokens expire based on Auth0 configuration. If you receive a 401 response, prompt the user to re-authenticate rather than retrying.
