Workspaces
A key belongs to exactly one workspace. What that means for multi-tenant apps, and how a Bitrix24 portal differs from a standalone workspace.
A workspace owns WhatsApp connections. An API key is issued against exactly one workspace, and everything the key can see or do is scoped to it — there is no way to ask about another one.
One key, one workspace, many connections
For a multi-tenant application this is the shape you want:
- One API key, not one per tenant. Do not mint a key per customer.
- One
POST /connectionsper tenant, including the very first one, each with its own freshIdempotency-Key. - Route inbound events by
connection_id— a stable cuid that appears on every REST response and every webhook payload. Map it to your own customer record; we mint the id, you map it. - New connections are usable immediately. The key's connection list is resolved live on each request, so there is nothing to refresh after a create.
Two kinds of workspace
Standalone workspace
Created when you register at developers.wasync.app. The API is the whole product: you create connections over REST and each connection carries its own licence.
Bitrix24 portal
Created when WASync is installed on a Bitrix24 portal. Connections are created by the portal admin inside WASync, and API access to a number is a paid add-on.
The difference shows up in exactly two places, and they are worth knowing before you write code against the wrong one:
Creating connections. POST /connections is standalone-only. On a Bitrix24
portal it answers 403 forbidden_portal_kind — the portal admin creates
connections in the WASync interface instead. Every other endpoint behaves
identically on both.
What makes a connection reachable. In a standalone workspace it is the
connection's own licence (trial or paid). On a Bitrix24 portal the portal's
subscription pays for the number in the CRM, and reaching that same number
through the API additionally needs the API add-on, at $12 per number per
month. Without it the connection is simply not in GET /connections.
Bootstrapping
With an API key there is no bootstrap step: the key is issued against your
workspace directly, so POST /connections creates the first connection as
readily as the tenth.
An OAuth grant is different by construction — it is only ever issued over connections that already exist, so an OAuth-only integration cannot create a workspace's first connection. That is the reason every quickstart here starts with a key.