Authentication

Wati APIs use Bearer Token authentication. Every API request must include a valid API token in the HTTP Authorization header.

This guide explains how to generate your API token and include it in your API requests.

Generate an API token

Before making API requests, you need to generate an API token from your Wati account.

Steps

1. Log in to your Wati account.

2. In the navigation menu, click API, or go to:

   Connector → API → Create API Token

   

3. On the API Tokens page, click Generate new token.

   

4. Enter a token name and select the required scopes (permissions), such as:

   • contacts:read
   • contacts:write
   • messagetemplate:read

5. (Optional) Set an expiry date for the token. For security, rotating tokens every 6 months is recommended.

6. Copy and securely store the generated token.

Authentication header

All API requests must include the following HTTP headers.

Example request

GET https://live-mt-server.wati.io/xxxxxx/api/v1/getContacts

	Authorization: Bearer eyJhbGciOiJIUzI1.......
	Content-Type: application/json

Example API Call (cURL)

```bash
curl --location 'https://live-mt-server.wati.io/xxxxxx/api/v1/getContacts' \
	--header 'Authorization: Bearer <your_api_token>' \
	--header 'Content-Type: application/json'

Using authentication in common tools

Postman

1. Open your API request.

2. Go to the Authorization tab.

3. Select Bearer Token as the type.

4. Paste your API token in the Token field.

5. Send the request.

Zapier, n8n, or any HTTP client

Add the following header to your request:

Using environment variables (recommended)

For security, store your API credentials as environment variables instead of hardcoding them in your source code.

Example:

WATI_API_ENDPOINT=https://live-mt-server.wati.io/xxxxxx/
WATI_API_TOKEN=eyJhbG1NiIsIn......

Example usage:

Authorization: Bearer $WATI_API_TOKEN

Endpoint permissions

Each API endpoint includes a Permissions section. Choose the narrowest listed permission that supports your integration; possession of a valid token alone does not guarantee authorization.

• Permissions listed with OR are alternatives, not a requirement to grant every scope. For example, direct-send messaging accepts api OR wati_integration:write OR conversations:write; payment-status and order-detail reads accept api OR payment:read.
• The API-token authentication path evaluates the configured identity-provider scope hierarchy; OIDC checks its granted scope claims directly. Do not assume that every token type expands permissions identically.
• Some endpoints have no endpoint-specific scope attribute. Their Permissions section explains the conditional OIDC api fallback rather than inventing a resource-specific scope.
• Roles, tenant access, subscription/feature gates, and other endpoint-specific checks remain applicable. A scope match is not a guarantee that these other checks pass.
• A 403 Forbidden can indicate insufficient permission or another authorization restriction. Check the endpoint's Permissions and Responses sections before broadening token access. An invalid or missing token is an authentication problem, normally reported as 401.

The OpenAPI security scheme remains HTTP Bearer authentication. Resource permissions are documented in endpoint prose and x-wati-permissions; they are not OAuth scope arrays on a Bearer security scheme.