IllumiChat uses Auth0 for identity management. Most API endpoints require an authenticated session.
Session Authentication
Session-based authentication is the primary method for browser-based applications. When a user logs in at beta.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 | beta.illumichat.com |
credentials: "include" in your fetch calls:
const response = await fetch("https://beta.illumichat.com/api/assistants", {
method: "GET",
credentials: "include",
});
API Key Authentication (Coming Soon)
API key authentication for server-to-server integrations is coming soon. Currently, all authenticated endpoints use session-based authentication via Auth0.
curl -X GET https://beta.illumichat.com/api/assistants \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json"
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.
