---
updatedAt: 2026-11-03T06:19:38.000Z
agentTools:
  projectIndex: https://docs.wati.io/llms.txt
---

# 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](https://docs.wati.io/reference/introduction#rest-api-regions).

| API            | Route form                                                                       |
| -------------- | -------------------------------------------------------------------------------- |
| V3             | `{API_HOST}/api/ext/v3/...` — no tenant ID in the path                           |
| Retained V1/V2 | Follow 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.

| Task                                          | Narrow scope named by that endpoint |
| --------------------------------------------- | ----------------------------------- |
| V3 contact list                               | `contactsv3:read`                   |
| V3 template list                              | `messagetemplatev3:read`            |
| V3 template send/schedule                     | `messagetemplatev3:write`           |
| Existing V1 `sendTemplateMessage` query route | `messagetemplate: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.

```bash
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

| Result                 | Next action                                                                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401                    | Check 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. |
| 403                    | Check the exact endpoint scopes, role, workspace and product/plan restrictions. Ask an administrator to confirm access before broadening permissions.                                                                           |
| 404/405                | Check host, tenant-prefix rules, path and method.                                                                                                                                                                               |
| 429                    | Follow [rate/usage recovery](https://docs.wati.io/reference/errors); credential rotation does not fix an exhausted quota.                                                                                                       |
| Timeout/5xx on a write | Preserve 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](https://docs.wati.io/reference/template-message-payload-guide).

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.