Authentication

Every /v1/instances/{instanceId}/... route requires the instance token in the Authorization header:

Authorization: Bearer TOKEN

The {instanceId} in the URL must be the instance that owns the token. A token from one instance cannot access another.

Account security token (optional)

If your account has a security token, send it too, in the x-account-token header:

Authorization: Bearer TOKEN
x-account-token: TOKEN_DE_SEGURANCA

You turn this token on and off in the dashboard, under Segurança (the dashboard is in Portuguese).

Allowed IP list (optional)

If the account has an allowed IP list, calls must come from one of those addresses. From any other address, the API responds 403 with ip_not_allowed. The list is also under Segurança in the dashboard.

Rotating the token

If the token leaks, generate a new one. The old one stops working immediately. You can do this in the dashboard or through the API:

curl -X POST https://api.zap.nigora.com.br/v1/instances/INSTANCIA_ID/token/regenerate \
  -H "Authorization: Bearer TOKEN"

The response is { "token": "..." }. The new value appears only in this response. Store it somewhere safe and update your systems.

Caution

Never put the token in code that runs in the browser or in your end customer’s app. Make the calls from your server.

Authentication errors

Status	Code	When it happens
401	invalid_token	Instance token missing, invalid, or from another instance
401	invalid_account_token	The account has a security token and x-account-token is missing or wrong
403	ip_not_allowed	The call’s IP is not in the account’s list
403	account_blocked	The account has been blocked; contact support (in Portuguese)
429	rate_limited	Too many consecutive authentication failures from the same IP (see Limits and errors)

In addition, routes that use the WhatsApp connection (connect, send messages, check contacts) respond 402 with instance_suspended when the instance is suspended or has a pending payment.