Authentication & scopes

The bearer key

Every Management API request must carry a wpk_live_… key in the Authorization header using the Bearer scheme:

Authorization: Bearer wpk_live_xxxxxxxxxxxxxxxxxxxx

curl https://www.wizchat.com/api/v1/chatbots \
  -H "Authorization: Bearer $WIZCHAT_API_KEY"

The SDKs add this header for you — you only supply the key:

import { createWizChatClient } from '@wizchat/management';
const wizchat = createWizChatClient({ apiKey: process.env.WIZCHAT_API_KEY! });

from wizchat_management import WizChatClient
wizchat = WizChatClient(api_key=os.environ["WIZCHAT_API_KEY"])

A missing or malformed key returns 401 Unauthorized.

Scopes

Management API keys are scoped. Each operation declares a required scope in its reference page (for example, List chatbots requires chatbots:read). A key that authenticates successfully but lacks the required scope receives 403 Forbidden.

Grant only the scopes a key actually needs. The available scopes are:

Scope	Grants
chatbots:read	Read chatbot settings and list chatbots
chatbots:write	Update chatbot settings
documents:read	List and read documents
documents:write	Add text/Markdown content, delete documents, and change privacy / authorized emails
videos:read	List and read videos
videos:write	Delete videos
mcp:read	Read MCP server config and access control
mcp:write	Create, update, delete MCP servers and their access control
skills:read	Read skills
skills:write	Create, update, delete skills
security:read	Read access-protection, external-API, access-list, and telemetry config
security:write	Update those security settings and manage their keys
domains:read	List authorized custom domains
domains:write	Authorize, deauthorize, and verify custom domains
deploy	Read deployment status and trigger a redeploy
analytics:read	Read cost and usage analytics

info

The config-as-code GET /config and POST /apply endpoints require the per-section read scopes for an export or dry-run, and the per-section write scopes (plus chatbots:write) to apply changes. A dry-run never needs write scopes.

Per-chatbot lock

A key is bound to the chatbots its owner can access. In the current phase, GET /api/v1/chatbots returns only the chatbots owned by the caller. Team-shared or individually-granted chatbots are still reachable by id via GET/PATCH /api/v1/chatbots/{chatbotId} but are not enumerated in the list.

Owner tokens

In addition to wpk_live_… keys, the API also accepts a Firebase ID token for owner-authenticated, first-party requests. For programmatic integrations, use a Management API key.

Rotating and revoking keys

Rotate keys periodically and whenever one may have leaked:

1. Create a new key with the same scopes.
2. Update your integration to use it.
3. Revoke the old key in the dashboard.

Revoked keys stop working immediately and return 401.