Authenticate with a Waaru API key

Create a key in Settings > Developer > API keys. Every key requires a WhatsApp number and at least one supported scope. The number must be connected and use Developer API as its inbound handler before requests can succeed.

Choose the supported scopes

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

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. These three API scopes control what the server may do. Dashboard permissions such as contact:read are not Developer API scopes.

Make a read-only request

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 connected, API-managed number with no 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 failures

• 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: choose Use Developer API for the bound number.
• 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.