API authentication

Create a key in Settings > Developer > API keys. Every key requires a WhatsApp number and at least one supported scope. Read scopes work with either inbound handler and can expose retained history after disconnection, subject to workspace, number, contact and data-retention lifecycle checks. Autonomous messages:send still requires a connected number using Developer API handling. Workspace resource mutations retain their existing write gates.

Choose the supported scopesCopy Anchor Link

A scope is a permission on the key. Select only the operations your integration needs from the table below.

Workspace-prefixed scopes expose shared workspace data, not just contacts for one number. A key manager can grant only scopes allowed by their current workspace role. Number grants do not authorize workspace data. Existing keys do not gain new scopes automatically.

Grant only the scopes the calling service needs. A send-only key cannot read message status; add messages:read if the service needs that check. To use another number, create another key bound to that number. Editing or rotating a key does not change its number.

Workspace roles control who can manage keys and number settings in the dashboard. The API scopes control what the server may do. Dashboard permissions such as contact:read are not Developer API scopes.

Make a read-only requestCopy Anchor Link

The example uses curl, a command-line tool for HTTP requests. Set WAARU_API_KEY in your service’s secret manager or local environment before running it. $WAARU_API_KEY reads that value; it is not a literal API key. The following request needs messages:read:

curl --fail-with-body 'https://api.waaru.app/v1/conversations?limit=10' \
  --header "Authorization: Bearer $WAARU_API_KEY" \
  --header 'Accept: application/json'

Expected result: HTTP 200 means the read request succeeded. A number with no visible retained conversations returns:

{
  "items": [],
  "nextCursor": null
}

Use the returned conversation identifiers in later calls. Knowing another workspace's identifier does not grant access. Send the Bearer header on every request; an API key cannot be replaced with your Google token, a Meta access token, or a dashboard cookie.

Diagnose access failuresCopy Anchor Link

• 401 with unauthorized or invalid_api_key: check the key value and whether it was rotated or revoked.
• 403 with insufficient_scope: compare the requested operation with the key's scopes.
• 403 with api_key_not_allowed: the route is not available to external API keys. Use the endpoint reference.
• 409 with instance_not_api_managed: a control or mutation request requires Use Developer API. Read-only observation does not require switching handlers.
• 409 with instance_unavailable: restore the number's connection.

Do not send secrets in query strings or paste them into support tickets. For rotation, revocation, and one-time secret display, follow Manage API keys. Continue with sending messages.

Grant lifecycle and discovery accessCopy Anchor Link

• workspace:labels:manage: create, rename and archive workspace labels.
• workspace:segments:manage: update and archive static workspace segments.
• instance:read: read the bound number's state, mode and granted scopes.

These scopes are opt-in. Existing keys receive no new grants. Your workspace permissions must permit the corresponding operation before you can grant it. Number status and capabilities remains available with instance:read when the number is disconnected or uses another inbound handler. Other scoped reads also work in either handler mode. Disconnection does not grant send authority, and deleted numbers or inactive workspaces remain inaccessible. campaigns:read is an explicit grant requiring the key manager's broadcast-read authority; it gives no send or scheduling permission.