Admin API: run every client and number from your own system

In short: an admin key does by API what an owner does in the ZapClaw dashboard. Your system creates a client, gives it an API key, sends the connect link, sets up the webhook (Chatwoot included) and reads the number once it connects. Your clients never open ZapClaw.

What an admin key can do

• Clients (agency accounts): create, rename, archive and reactivate them, each with your own externalId.
• Connect links: the page where your client logs in to Facebook and scans the QR code, with an optional button back to your system.
• Numbers: health, limits, Phone Number ID and WABA ID; rename, disconnect and move them between clients.
• Client API keys: create and revoke the zc_live_ keys your integrations send with.
• Webhooks: your own endpoint or Chatwoot, the signing secret, tests and resends.
• Everything a client key already does, for any client: templates, sending, media, profile, QR codes, usage and logs.
• Account events on a webhook of your own: a number connected, disconnected or restricted, a link that expired.

Some things stay with a person in the dashboard on purpose: the password and two step sign in, deleting the account, billing and payments, accepting terms and approving what an AI agent wants to send.

Authentication

Send the key in the X-API-Key header. Admin routes live under https://api.zapclaw.app/api/v1/admin and name the client in the path. On the routes a client key already calls, add X-Client-Id to say which client you act on.

curl https://api.zapclaw.app/api/v1/admin/clients \
  -H "X-API-Key: $ZAPCLAW_ADMIN_KEY"

An admin key sent in a URL is refused and flagged as exposed. A key with a list of IP addresses only answers calls from them.

Permissions

Each key holds only the permissions ticked when it was created. Full administration ticks them all; Connect and set up clients ticks what a signup flow needs.

• clients:read, clients:write: see and change clients.
• numbers:read, numbers:write: numbers, health and limits; rename, disconnect, move, profile, QR codes, automations and blocks.
• links:read, links:write: connect links and their history.
• keys:read, keys:write: client API keys.
• webhooks:read, webhooks:write, webhooks:secret: webhooks, deliveries and the signing secret.
• templates:read, templates:write, messages:read, messages:send: templates and messages of any client.
• usage:read, billing:read, audit:read: usage, the limits per client, logs, plan, invoices and the account activity (billing is read only).

Main endpoints

GET    /api/v1/admin/key                                        the calling key
GET    /api/v1/admin/clients                                    clients:read
POST   /api/v1/admin/clients                                    clients:write
PATCH  /api/v1/admin/clients/{clientId}                         clients:write
POST   /api/v1/admin/clients/{clientId}/keys                    keys:write
POST   /api/v1/admin/clients/{clientId}/links                   links:write
GET    /api/v1/admin/clients/{clientId}/links/{linkId}          links:read
GET    /api/v1/admin/clients/{clientId}/numbers                 numbers:read
PUT    /api/v1/admin/clients/{clientId}/webhooks/{mode}         webhooks:write
GET    /api/v1/admin/clients/{clientId}/webhooks/{mode}/secret  webhooks:secret
GET    /api/v1/admin/clients/{clientId}/numbers/{numberId}/chatwoot-inbox numbers:read + webhooks:secret
PUT    /api/v1/admin/event-endpoint                             webhooks:write
GET    /api/v1/admin/activity                                   audit:read

Bodies, answers and errors of every route are in the API reference and in openapi.yaml.

Secrets are shown once

A new admin key, client key or connect link comes back once, in the answer that creates it, and ZapClaw keeps only its hash. A webhook signing secret is the one secret you can read again, with webhooks:secret, and every read shows in the account activity.

Know when a number connects

Register one account events webhook and ZapClaw posts to it, signed in the X-ZapClaw-Signature header with its own secret: client_link.used, number.connected, number.disconnected, number.restricted and client_link.expired. You can also read the link: its status turns connected and it names the number.

Safety

• Only the owner or an admin creates a key, confirming with the password and, when it is on, the two step code. The owner gets an email.
• Up to 10 active admin keys per account. A revoked key stops at once.
• Every change made with a key shows in Settings, Activity, under the key's name.
• A key never reaches another account, and every client it names is checked against yours.
• When the person who created a key is no longer an owner or admin, the key stops.