Wabery authentication

API keys authenticate your requests. A signing secret verifies Wabery’s webhooks. Do not use one in place of the other.

Self-serve API key generation

Create a project key yourself:

1. Sign up on the free tier — no credit card.
2. Open Access → API keys.
3. Generate a wab_live_ secret key or a wab_pub_ publishable key, copy it once, and store it as WABERY_API_KEY.

The Wabery sandbox test environment works with the same keys before you connect a production WhatsApp number.

Get a project key with the CLI

If you work from a terminal, the CLI can create and store the project key:

npm i -g @wabery/cli
wabery login   # opens the browser, choose a project, paste the shown key once

wabery login creates an API key for the project you select and stores it in your local CLI config, so the CLI and the MCP server are authenticated automatically after that first paste. Use wabery doctor to confirm it works. Create projects in the dashboard, then open Access → API keys to create, reveal, scope, or revoke a project key.

API keys

Keys are prefixed by capability:

Prefix	Use
wab_live_	Server-side API access in the shared sandbox and on connected channels.
wab_pub_	Browser-safe publishable key for registration intents.

For your own services, set WABERY_API_KEY (it overrides the CLI config) and authenticate every request with a Bearer token:

curl https://api.wabery.com/v1/messages \
  -H "Authorization: Bearer $WABERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel_id": "channel_...", "conversation_id": "conversation_...", "text": "Hi" }'

The SDK reads the key for you:

import { Wabery } from "@wabery/sdk";

const wabery = new Wabery();

Cuidado

wab_live_ keys are server-side secrets. Don’t expose them in client code, mobile apps, or git history. Rotate immediately if one leaks.

Publishable keys

Publishable keys (wab_pub_...) are safe to use in browser widgets, but only on the registration-intent endpoints. Send them in the x-wabery-publishable-key header, not as a Bearer token:

curl https://api.wabery.com/v1/registration-intents \
  -H "x-wabery-publishable-key: $WABERY_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer_reference": "user_123" }'

The SDK and CLI do this automatically when apiKey / WABERY_API_KEY starts with wab_pub_.

Webhook signing secret

Each webhook endpoint has a signing secret. Wabery signs every delivery so you can confirm it really came from Wabery and wasn’t tampered with — the signature arrives in the x-wabery-signature header as sha256=<hex>. See Webhooks for verification.

Scopes

API keys carry a set of scopes that limit blast radius. A request missing the required scope returns 403 with error: "insufficient_scope" and the required_scope in the body. Grant the narrowest set each integration needs:

Scope	Grants
messages:send	Send messages.
conversations:read	List conversations and read message history.
contacts:read / contacts:write	Read / enroll and update contacts.
contacts:erase	Erase a contact’s retained personal data.
broadcasts:read / broadcasts:write / broadcasts:send	Read / create and manage / deliver broadcast campaigns.
templates:read / templates:write	Read / create WhatsApp templates.
channels:read / channels:write	List and inspect / update channel routing.
business_agents:read / business_agents:write	Inspect / provision and manage Meta Business Agents, connectors, tools, settings, thread control, and skills.
flows:read / flows:send / flows:publish	Read / send / publish WhatsApp Flows.
functions:read / functions:write / functions:invoke	Read, deploy/manage, and invoke hosted functions.
submissions:read / dispatches:read	Read Flow submissions / dispatches.
projects:read / projects:write	Read / update project settings (webhook URL, routing).
config:read / config:write	Read / apply config-as-code.
registrations:create	Mint registration intents (also granted to wab_pub_ keys).
limits:read	Read the key’s rate limits and quota.

A wildcard (*) key grants every scope — use it only for trusted server-side automation.