IllumiChat - AI-Powered Chat Platform

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`

For browser-based integrations, include 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"

const response = await fetch("https://app.illumichat.com/api/v1/contacts", {
  headers: {
    Authorization: "Bearer wsk_live_xxxxxxxxxxxxxxxx",
    "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 governs access to the assistant in the internal Chat workspace, not the embeddable widget (which is controlled by widgetEnabled).

Visibility	Who Can Access
`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.

Getting Started

Endpoints

Authentication

Session Authentication

API Key Authentication

Creating a key

Making authenticated requests

Scopes

Revoking a key

Public Endpoints

Widget Endpoints

SMS Webhooks

Authorization

Workspace Roles

Assistant Visibility

Auth Error Responses

​Session Authentication

​API Key Authentication

​Creating a key

​Making authenticated requests

​Scopes

​Revoking a key

​Public Endpoints

​Widget Endpoints

​SMS Webhooks

​Authorization

​Workspace Roles

​Assistant Visibility

​Auth Error Responses

Session Authentication

API Key Authentication

Creating a key

Making authenticated requests

Scopes

Revoking a key

Public Endpoints

Widget Endpoints

SMS Webhooks

Authorization

Workspace Roles

Assistant Visibility

Auth Error Responses