API keys and Client ID

An API key lets your own software, and tools such as Zapier, n8n, Make and the WordPress plugin, send WhatsApp messages from your workspace's numbers. Your own code sends the key in an Authorization: Bearer header; integrations ask for two values from the API keys page: your workspace's Client ID and one of its keys. The same page has the secret that signs our webhooks.

Who can do it: Owners only – every Owner of the workspace, not just its creator. Owners see, create, copy and delete all of the workspace's keys, whoever created them. Editors and Analysts don't see API keys in the sidebar or on the Settings page, and a link to it opens Profile for them (see Roles and permissions). Keys work on every plan, including the free trial; what you send with them uses the workspace's messages.

Open API keys under Integrations in the sidebar, or go to Settings → API keys.

Each key shows its name, when it was Created, the last four characters of the key (such as •••• 7f3a), Copy key and Delete. The newest key comes first.

Create an API key#

1. Click Create key

   On Settings → API keys, click Create key at the top right of the card.

2. Name it (optional)

   Under Name (optional), type the app that will use it, such as n8n or Website (up to 50 characters). Left empty, it gets a name such as "API Key 3", as the hint under the field says.

3. Create it

   Click Create key.

   

4. Copy the key

   Your new API key shows the full key: "Copy it now – you won’t see the full key again. Later, “Copy key” copies it without showing it." Click Copy ("Key copied."), paste the key into your app or integration, then click Done.

   

• Up to 10 keys per workspace. With 10, Create key is greyed out, and pointing at it shows "You can have up to 10 API keys. Delete one to create another."
• Keys don't expire, and they can't be renamed or switched off: a key works until it's deleted.
• One key per app. Name each key after the app that uses it, so you can replace or delete one without breaking the others.
• Which workspace: a key belongs to the workspace that was selected when you created it, and every request made with it acts on that workspace: its numbers, messages and plan. To send from another workspace, switch to it and create a key there.

What to enter in your app#

Where they go:

• Your own code: in an Authorization: Bearer YOUR_API_KEY header on every request (recommended). The key names its workspace, so client_id can be left out; if you send it, it must still be this workspace's. See Send the key in a header, and Send message for a first message in cURL, Python, Node.js and PHP.
• Zapier: the Client ID and API key when you connect your account.
• n8n: the WbizTool credential's Client ID, API Key and WhatsApp Client ID.
• Make, Pabbly Connect and other tools: the body of an HTTP request.
• WordPress: WbizTool → Settings, under API Configuration.

Google Sheets and Shopify are set up in the dashboard and don't need a key.

Send the key in a header#

Every /api/v1/ endpoint takes the key in an Authorization header, the way the coming API v2 will:

Authorization: Bearer YOUR_API_KEY

• client_id is optional with the header: the key decides the workspace. If you also send client_id, it must be this workspace's Client ID, as before.
• Send the key in one place. With the header, leave api_key out of the body, or send the same key. If they differ, the header's key is used when it's a valid key; if the header holds something else (another tool's token, say), the body's api_key is used.
• Keys in the body still work (client_id and api_key as JSON or form fields), so nothing changes for apps and integrations that send them. The header is better because request bodies end up in logs, proxies and form-builder histories more often than headers.
• Form fields, multipart uploads and JSON bodies all work with the header.

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_client": 101, "phone": "919876543210", "msg": "Hello from WbizTool"}'

Test your key#

Call Check credentials (POST /api/v1/me/) with your key and, if you like, a whatsapp_client. "status": 1 with "message": "Okay" means they work together. It sends nothing and uses no messages, but it doesn't check that you have messages left or that the number is connected.

curl -X POST https://wbiztool.com/api/v1/me/ -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{"whatsapp_client": 101}'

A working key answers {"status": 1, "message": "Okay", "name": "…"}.

Copy a key again#

Click Copy key next to the key. The full key goes to your clipboard without being shown on the page; you see, for example, "“Zapier” copied." and the button shows Copied ✓ for a moment. You don't need a new key because you lost the old one.

To find out which key an app uses, compare the last four characters of its key with the list.

Delete a key#

1. Click Delete

   Click Delete next to the key.

2. Confirm

   The dialog "Delete “…”?" warns: "Anything using this key stops working straight away: Zaps in Zapier, n8n and Make scenarios, the WordPress plugin and your own API calls. Give them another key first. This can’t be undone." Click Delete key. You see "“…” deleted."

From then on, requests with that key get Auth Error: invalid api key. What it did earlier stays: messages it queued still go out (cancel them in Reports if you need to), and reminders it created keep running. A Zapier Incoming WhatsApp Message trigger set up with it also keeps receiving messages, because its webhook is already on the number: turn the Zap off in Zapier to stop it.

Replace a key#

Replace a key when it may have leaked, when someone who could copy it leaves, or from time to time. There's no rotate button: create the new key first, so nothing stops in between.

1. Create a new key

   Create a key and copy it. With 10 keys, first delete one you no longer use.

2. Update your apps

   Paste the new key into every app and integration that used the old one, and check each of them, for example with Check credentials.

3. Delete the old key

   Delete it. It stops working at once.

4. Check for misuse (after a leak)

   Look through Reports for messages you didn't send and cancel any still waiting. On Reminders, delete reminders you didn't create, because they keep running. Remove numbers you didn't add on WhatsApp numbers. With the Unibox add-on, look on Inbox numbers for a Zapier badge or webhook you don't recognise.

Keep your keys safe#

A key has no permissions of its own: anyone who has one can do everything the API can in your workspace, whatever their role. That includes sending messages from any of its numbers (using its messages), reading its message history, cancelling waiting messages, managing reminders and media files, checking numbers and connecting new ones.

• Keep keys on your server, in an environment variable or your integration's credential store. Never put one in a website's JavaScript, a mobile app, a shared spreadsheet or code you publish.
• Don't send keys by email or chat. Paste them straight into the app that needs them.
• Use one key per app, and delete keys you no longer use.
• Replace keys from time to time, and at once if one may have leaked.

The Client ID alone isn't a secret, but treat every key like a password.

API v2 keys#

API v2 has its own keys, made in the API v2 keys card on the same tab. They're safer than the keys above:

• Shown once. The full key (wbz_live_…) is shown only when you make it; WbizTool keeps just a fingerprint. If you lose it, revoke it and make a new one.
• Only what it needs. Tick what the key may do (send messages, read messages, reminders, numbers, media, number checks), limit it to some of your numbers, and give it an expiry date if you like.
• Test keys. A test key (wbz_test_…) checks every request like a live key but sends nothing – for building and trying out an integration.
• Last used. Each key shows when and from where it was last used. Revoke stops it at once, and the webhook endpoints it set up with it.

The keys above work only with API v1, and API v2 keys only with v2. See Moving from v1 to v2.

Webhook signatures#

WbizTool signs every webhook it sends you, so your endpoint can check that a request really came from us and wasn't changed on the way: the message status webhook (sent, failed, cancelled, expired), the number connection events and the Inbox webhooks. The bodies are the same as before; two headers are added:

The signature covers the exact bytes we send: form fields as they arrive, the whole multipart body when a QR code image is attached, and the JSON of Inbox webhooks. Receivers that ignore the headers keep working.

Get the signing secret#

On Settings → API keys, the Webhook signing secret card under your keys shows the last four characters of the secret, such as •••• b70d. Every workspace has one secret for all its webhooks; it's made with the first webhook we send you.

1. Click Reveal new secret

   Click Reveal new secret (or Create secret if the workspace has none yet). The dialog "Replace the signing secret?" warns that the current secret stops working straight away. Click Make new secret.

2. Copy it

   Your webhook signing secret shows the full secret once. Click Copy and store it where your webhook receiver can read it, such as an environment variable. You won't see it again: if you lose it, make a new one.

Only Owners see the card. Making a new secret replaces the old one at once, so update your receivers straight after; webhooks sent in between fail your check.

Check a webhook#

Work out the signature from the raw body (before your framework parses it), compare it with the header in constant time, and refuse timestamps older than 5 minutes so an old request can't be replayed:

import hashlib, hmac, time

def verify(secret: str, body: bytes, headers) -> bool:
    ts, sig = headers["WbizTool-Timestamp"], headers["WbizTool-Signature"]
    mac = "v1=" + hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(ts)) < 300 and hmac.compare_digest(mac, sig)

const crypto = require("crypto");

function verify(secret, rawBody, headers) {
  const ts = headers["wbiztool-timestamp"], sig = String(headers["wbiztool-signature"]);
  const mac = "v1=" + crypto.createHmac("sha256", secret).update(ts + ".").update(rawBody).digest("hex");
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300 && sig.length === mac.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(mac));
}

Answer 2xx when the check passes and 401 when it fails. Inbox webhooks with their own listener secret still carry X-Wbiztool-Signature as well; WbizTool-Signature is the same scheme on every webhook.

Troubleshooting#

Related#

• Getting started with the API
• API v2 overview
• Check credentials API
• Send message API
• Apps & integrations
• Workspace settings, team members and roles
• Connect your WhatsApp number