Authentication

Every request to the WaConnect API is authenticated with an API key, sent in the Authorization header as a bearer token.

curl https://api.waconnect.ai/v1/me \
  -H "Authorization: Bearer wc_live_your_key"

Create a key#

Admins create keys in Settings → Developer settings → API keys. Each key:

• starts with wc_live_ followed by 43 random characters;
• is shown once, when it's created — we only keep a fingerprint of it, so it can't be shown again;
• acts for your business: it can use all of its numbers, or only the numbers you pick.

Create one key per system (for example "Production CRM" and "Staging"), so you can revoke one without touching the others.

Limit a key to some numbers#

API keys only ever use API numbers; inbox numbers don't exist for them. When several apps share one business, each with its own WhatsApp numbers, limit each app's key to its numbers. Pick the numbers when you create the key, or later with Numbers next to the key in Developer settings. A limited key:

• lists only its numbers in GET /v1/numbers;
• can only send from its numbers. Any other number answers 404 with the code NUMBER_NOT_FOUND, exactly as if it didn't exist;
• only downloads files of its numbers' messages (GET /v1/messages/:id/media);
• only sees webhooks that receive events for at least one of its numbers (GET /v1/webhooks);
• adds every number it connects with POST /v1/numbers to its own list.

GET /v1/me shows which numbers the key can use, in key.numbers: "all", or a list of number ids.

{
  "business": { "id": "01a0f44d-0000-7000-8000-000000000001", "name": "Brooklyn Dental" },
  "key": { "name": "Booking app", "prefix": "wc_live_8f3k", "numbers": ["01a0f44d-c969-75b1-955d-3841d817f711"] },
  "credits": { "balanceCents": 2500, "balanceUsd": "25.000" }
}

Pair this with webhooks limited to the same numbers, so each app only receives its own events.

Revoke a key#

Click Revoke next to the key in Developer settings. It stops working immediately, and requests with it get 401.

If a key leaks, revoke it and create a new one — there's no way to "rotate" a key in place.

Authentication errors#

Who can manage keys#

Only admins of a business can see, create and revoke API keys and webhooks. Team members with the Agent role don't see the Developer settings page.