Authenticate with a ChatWith API key

Create an API key

In the dashboard, open Settings → API. Only workspace owners and admins can create keys (the default name is "MCP key"). You can also mint keys through MCP with create_api_key when your role allows it.

ChatWith stores only an HMAC-SHA256 hash with a server pepper, so the full secret appears once when you create the key — the same thing the Settings → API panel says. Set expires_at to a future timestamp for a key that stops working after a date; expired keys return UNAUTHENTICATED.

Send the key as a bearer token

Every ChatWith API and MCP request must send your key in the Authorization header as Authorization: Bearer cw_live_… (the prefix cw_live_ plus 64 hex characters), following bearer-token usage in RFC 6750. It is the same credential for Streamable HTTP clients and raw HTTP calls.

curl -sS -X POST 'https://YOUR_PROJECT.supabase.co/functions/v1/mcp' \
  -H 'Authorization: Bearer cw_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "example", "version": "1.0" }
    }
  }'

What the key can do

Keys inherit the workspace role of the user who created them: owner, admin, member or viewer. Viewers may call read-only and ask tools; admins manage webhooks and API keys; only owners delete the workspace.

Plan gates apply on top of roles: lead tools and insights metrics need Pro or Agency; webhooks, team invites and client workspaces need Agency; Growth is the minimum plan for MCP access at all.

Rate limits

Limit	Value
MCP requests per API key	60/min
Failed auth attempts per IP	30/min
ask_assistant / ask_published_assistant	20/min
Knowledge source creates	15/hour
test_webhook	10/hour
API key creation	10/hour

Rotate and revoke keys

List keys with list_api_keys and revoke with revoke_api_key. Each workspace can hold up to 20 active keys. Create a replacement before revoking a key that is in production.

Errors you can get

Only authentication, transport and rate limits use HTTP status codes. After you are authenticated, any other tool-level failure is returned as HTTP 200 with a JSON-RPC error (top-level code -32000, and a data.code naming the cause); a tool-level rate limit is the exception and comes back as HTTP 429.

• 401 UNAUTHENTICATED (HTTP) — a missing or invalid bearer token, a revoked or expired key, or a key whose creator is no longer a member of the workspace.
• 402 PLAN_REQUIRED (HTTP) — a workspace without an active paid plan.
• 429 RATE_LIMITED (HTTP) — rate limited; retry after the Retry-After header.
• PLAN_LIMIT_REACHED (data.code) — the conversation quota is exhausted on a persisted ask.
• FORBIDDEN or PLAN_FEATURE (data.code) — insufficient role or plan for the tool.

Why API keys and not OAuth

The MCP authorization spec describes OAuth for HTTP transports (MCP Authorization). ChatWith uses static workspace API keys today; integrations should not assume OAuth is available yet.

Keep your key safe

Store keys in environment variables or a secret manager, never in client-side code or public repositories. The OWASP REST Security Cheat Sheet and OWASP API Security Project apply even though ChatWith is JSON-RPC, not REST.

Next: the ChatWith API overview, the MCP server, or MCP use cases.