> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illumichat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate API requests

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:

```javascript theme={null}
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](/features/zapier). A key acts on behalf of the whole workspace, not an individual user.

<Note>
  API keys use a static bearer token — there is **no OAuth2 flow**. Auth0 sessions remain the mechanism for browser and in-app requests.
</Note>

### 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.

<Warning>
  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`.
</Warning>

### Making authenticated requests

Send the key as a bearer token:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://app.illumichat.com/api/v1/contacts \
    -H "Authorization: Bearer wsk_live_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://app.illumichat.com/api/v1/contacts", {
    headers: {
      Authorization: "Bearer wsk_live_xxxxxxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
  });
  ```
</CodeGroup>

### 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:

### Widget Endpoints

| 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 |

<Note>
  SMS webhook endpoints validate the **Twilio request signature** to verify that incoming requests originate from Twilio.
</Note>

## 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 |

<Warning>
  Session tokens expire based on Auth0 configuration. If you receive a `401` response, prompt the user to re-authenticate rather than retrying.
</Warning>