Skip to main content
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. 
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: 
{
  "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.