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

# Authentication

> How authentication works in the Whilst API

Whilst uses two authentication methods depending on the context.

## Session-Based (Web App)

After logging in through WorkOS, a JWT session cookie (`whilst_session`) is set automatically. This is used for all web app API calls.

```typescript theme={null}
interface Session {
  userId: string;      // UUID of the authenticated user
  accountId: string;   // UUID of the user's workspace/tenant
  email: string;
  role: 'admin' | 'member' | 'viewer';
}
```

## API Key (MCP Server)

For programmatic access via the MCP Server, workspace-scoped API keys are used.

### Key Format

```
whl_live_abc123def456...  (production)
whl_test_xyz789...        (development)
```

* Prefix: `whl_` (whilst)
* Environment: `live_` or `test_`
* Random: 32 bytes, base64url encoded

### Key Management

Generate and manage API keys from **Settings → API Keys** in the web app. Keys support granular permissions:

* `docs:read` — Read documents
* `docs:write` — Create and edit documents
* `folders:read` — Read folders
* `folders:write` — Create and edit folders
* `search` — Execute search queries

### Usage

Pass the API key in the environment when connecting your MCP client:

```json theme={null}
{
  "mcpServers": {
    "whilst": {
      "command": "npx",
      "args": ["@whilst/mcp-server"],
      "env": {
        "WHILST_API_KEY": "whl_live_your_key_here"
      }
    }
  }
}
```

## Slack Signature Verification

Bot-facing endpoints verify the `X-Slack-Signature` header using Slack's signing secret. This is handled internally by the Event Intake Lambda.