Authentication

All Watsi API requests require a Bearer token. This guide covers how to create API keys, authenticate requests, and keep your credentials secure.

Creating an API key

Sign in to the Watsi dashboard
Navigate to Settings → API Keys
Click Generate new key
Copy the key immediately — it is displayed only once

Important: Store your API key in a secure location such as an environment variable or secret manager. Never commit API keys to source control.

Using your API key

Include the API key in the Authorization header of every request using the Bearer scheme:

curl https://api.watsi.ai/api/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY"

If the key is missing or invalid, the API returns a 401 Unauthorized response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Unauthorized"
  }
}

API key scopes

Each API key is scoped to a single workspace. The key inherits the permissions of the user who created it and can access all resources within that workspace.

Scope	Access
`conversations`	List, read, and manage conversations
`customers`	List, read, create, and update contacts
`messages`	Send messages within open conversations
`templates`	List and manage WhatsApp message templates
`tags`	Create, list, and assign tags to contacts
`users`	List workspace team members

MCP authentication

The same API key works for MCP (Model Context Protocol) connections. Add it to your MCP client configuration:

{
  "mcpServers": {
    "watsi": {
      "url": "https://mcp.watsi.ai/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

The MCP server now mirrors the shipped public API action surface for contacts, conversations, appointments, calendar embeds, campaigns, knowledge, and analytics. That lets AI clients use the same workspace key for both read and write workflows instead of relying on a separate private integration path.

Contacts: list, search, get, create, update, delete, channels, and batch import tools
Conversations: update, close/reopen, notes CRUD, and summary tools in addition to the existing read/search helpers
Scheduling: appointments, appointment types, calendar spaces, widget embed metadata, and iCal token rotation
Campaigns / knowledge / analytics: execution, lifecycle, and export tools aligned with the public REST endpoints

When a tool expects a request body, pass the same JSON payload you would send to the matching REST endpoint. File uploads are supported through base64 content plus filename and content type fields.

Security best practices

Rotate keys regularly — generate a new key and revoke the old one periodically
Use environment variables — never hardcode keys in application source code
Restrict server-side usage — never expose API keys in client-side code or browser requests
Monitor usage — review API key activity in the dashboard and revoke any keys you no longer need
Use HTTPS only — all API requests must be made over HTTPS. Plain HTTP requests are rejected

Rate limits

The API allows 100 requests per minute per API key. When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

See the error handling guide for retry strategies.