Authentication & Keys
The Zingasuite MCP server authenticates with the same zk_ API keys as the REST API. The agent sends the key as a bearer token on every request:
Authorization: Bearer zk_live_xxxxxxxxxxxxxxxxxxxxxxxx
The acting entity is derived from the key — there's no workspace to choose in the client.
Create a key for your agent
The easiest way is Console → Settings → Connect AI Agents:
- Choose read-only (recommended) or read-write.
- Click Generate MCP key.
- Copy the token — it's shown once — and paste it into your client's config (the page fills it in for you).
You can also mint keys the usual way under Settings → API Keys; see API Keys.
Scopes decide what the agent can do
A key's scopes are the ceiling on the agent's abilities. The presets:
| Preset | Scopes | The agent can… |
|---|---|---|
| Read-only | data:read, messaging:read |
read catalog/orders/inventory, search docs, list channels — but change nothing |
| Read-write | data:read, data:write:*, messaging:read, messaging:send |
also create/update products, import orders, adjust stock, send WhatsApp |
You can also craft narrower scopes (e.g. data:write:products only). Messaging lives in a separate messaging:* namespace on purpose — a shop key can't send messages, and a messaging key can't read shop data. A key can never exceed the role of the member who created it.
Live vs test
zk_live_… keys act on real data; zk_test_… keys are for sandbox use. Point experiments at a test key first.
Rotating & revoking
Keys can be revoked anytime from the console; a revoked key stops working immediately, as does any key whose owner loses access to the entity. Set an expiry when you create a key if the agent only needs temporary access.