Authentication

Generate a WATI API token, send the Bearer header, and select the permissions required by each endpoint.

Use an API credential from the same WATI workspace and region as your API host. Send it as Authorization: Bearer <token>. Product MCP OAuth is a separate connection flow; a docs-MCP connection does not authenticate business API calls.

Create and store a token

  1. In your workspace, open API → API Tokens (also available through Connector → API). If token management is unavailable, ask your workspace administrator.
  2. Create a separately named token for the integration. Select the endpoint's required scopes and the expiry option available to your role/account. An expiry can be required; it is not optional for every user. Record the selected expiry and schedule replacement before it.
  3. Copy the new secret when it is shown and save it in your server's secret manager or environment. It is shown once. Keep the API host and workspace identifier with the integration configuration, separately from the secret.

Never place a token in a URL, frontend bundle, agent prompt, repository, screenshot or support message. For an agent, have the application inject the credential into HTTP headers at execution time.

Match the host and route

Use your workspace's configured API host; dedicated hosts take precedence over the standard regional hosts.

APIRoute form
V3{API_HOST}/api/ext/v3/... — no tenant ID in the path
Retained V1/V2Follow the documented /{tenantId}/api/v1/... or /{tenantId}/api/v2/... route

Store WATI_API_HOST as the host only, without a tenant ID or /api suffix. Do not move a token between accounts/regions or use the application-login/MCP host as the REST host.

Choose permissions and verify access

Use the operation's Permissions section. Scopes listed with OR are alternatives. Roles, workspace, product/channel access and plan restrictions still apply.

TaskNarrow scope named by that endpoint
V3 contact listcontactsv3:read
V3 template listmessagetemplatev3:read
V3 template send/schedulemessagetemplatev3:write
Existing V1 sendTemplateMessage query routemessagetemplate:write

The endpoint may also list broader alternatives such as api or wati_integration:write. A template read scope does not by itself grant sending. Existing legacy credentials and scoped tokens can follow different authorization paths; do not infer credential support from the API version alone.

For a low-impact check, choose a documented read operation your token is authorized to use. This example requires V3 contact-read access; a send-only token failing it does not prove the token is invalid. Do not grant unrelated scopes just to make a health check pass.

curl --silent --show-error --include \
  "${WATI_API_HOST}/api/ext/v3/contacts?page_number=1&page_size=1" \
  --header "Authorization: Bearer ${WATI_API_TOKEN}"

Keep returned contact data private. Avoid verbose HTTP logging that prints the Authorization header.

Rotate without assuming an overlap window

For planned rotation, when your role and token allowance permit it:

  1. Create a replacement under a different name with the required scopes/expiry; save the new secret securely.
  2. Verify a permitted low-impact operation and update the integration's secret/configuration. Confirm each consumer has switched.
  3. Revoke the old token through token management after dependent consumers are updated. Check the result and integration health; do not assume instantaneous propagation.

Regenerate is a different operation. Plan for interruption: do not assume old and new credentials overlap or that a failed regeneration leaves the old credential usable. Check the operation result before retrying, then update every consumer.

Disablement, expiry and revocation can stop requests. If a credential is exposed, promptly use the applicable revocation flow and replace it. Password changes are not a substitute for checking/revoking API credentials; existing legacy user-bound tokens can behave differently. Legacy token controls are separate from scoped-token management; do not assume an endpoint named rotateToken returns a replacement secret.

Diagnose before replacing credentials

ResultNext action
401Check missing/duplicated Bearer, whitespace, secret configuration, token expiry/status, workspace and region. Some endpoints also reject account/role states with 401. Do not automatically regenerate a token for every 401.
403Check the exact endpoint scopes, role, workspace and product/plan restrictions. Ask an administrator to confirm access before broadening permissions.
404/405Check host, tenant-prefix rules, path and method.
429Follow rate/usage recovery; credential rotation does not fix an exhausted quota.
Timeout/5xx on a writePreserve the previous attempt and reconcile its outcome before resending.

Authentication/authorization bodies can be empty, plain text or JSON. Check HTTP status before parsing JSON. Once the underlying issue is corrected, retry deliberately; repeated authentication failures need investigation, not an unlimited retry loop.

For an existing V1 template integration, use the documented sendTemplateMessage?whatsappNumber=... query route. A similarly named sendTemplateMessage/{whatsappNumber} action has different role support; do not assume scoped tokens work with both. New integrations should use the V3 template contract.

For persistent problems, send support the timestamp/timezone, region, method/path, HTTP status and a safe request/correlation ID. Include no token, Authorization header or customer message content.