Authentication

Every request to the SanadWA API must include an API key. The key tells SanadWA which account the request belongs to and what it may do.

Send the key in the Authorization header

Send the key as a bearer token in the Authorization header:

Authorization: Bearer pk_live_YOUR_KEY

• The word Bearer, one space, then the key. The word Bearer must be written exactly like this (capital B).
• Do not send the key in the URL or in the request body.

curl

curl https://api.sanadwa.com/v1/health \
  -H "Authorization: Bearer $SANADWA_API_KEY"

Node.js

const res = await fetch("https://api.sanadwa.com/v1/health", {
  headers: { Authorization: `Bearer ${process.env.SANADWA_API_KEY}` },
});

Python

import os
import requests

res = requests.get(
    "https://api.sanadwa.com/v1/health",
    headers={"Authorization": f"Bearer {os.environ['SANADWA_API_KEY']}"},
    timeout=30,
)

PHP

<?php
$ch = curl_init("https://api.sanadwa.com/v1/health");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer " . getenv("SANADWA_API_KEY")]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$body = curl_exec($ch);

If the header is missing, you get 401 api_key_missing. If the key is wrong or was revoked, you get 401 api_key_invalid. See Errors.

Create an API key

Only an admin of your SanadWA account can create keys, and your plan must include API access.

1. In the console, open Settings → Developers → API keys.
2. Click New API key.
3. Fill in the form:
   • Name: where the key is used, for example Order system.
   • Scope: what the key may do. See Scopes below.
   • IP allowlist (optional): see IP allowlist below.
   • Rate limit (req/min): leave it empty to use the default of 60 requests per minute. See Rate limits.
4. Click Mint key.
5. Copy the key. It starts with pk_live_. The console shows it only once. SanadWA stores only a fingerprint of the key, so nobody can show it to you again. If you lose it, create a new key.

You can create several keys, for example one per system. This lets you revoke one system’s access without touching the others.

Scopes

Each key has one scope. The scope decides which endpoints the key may call. Scopes are ordered: full can do everything send can do, and send can do everything read can do.

Scope	Console label	What it allows
read	Read	Every GET endpoint: /health, /balance, /phone-numbers, /templates, /messages/{id}, /tags, /contacts, /campaigns, /campaigns/{id}
send	Send	Everything read allows, plus the endpoints that send messages or spend credits: POST /messages/template, POST /messages/text, POST /campaigns, POST /campaigns/{id}/pause, POST /campaigns/{id}/resume
full	Full	Everything send allows, plus the endpoints that create, change or delete data in your account: POST /tags, DELETE /tags/{id}, POST /contacts, POST /contacts/import, DELETE /contacts/{id}

GET /openapi.json (the API description) needs no key.

If a key calls an endpoint its scope does not allow, the API returns 403 api_scope_insufficient.

Which scope should I use? Give each key the lowest scope that works:

• A system that only reads (for example a report of campaigns or a balance alert): read.
• A system that sends messages or campaigns to contacts that already exist: send.
• A system that also creates or updates contacts and tags: full.

You cannot change the scope of an existing key. Create a new key with the scope you need.

IP allowlist

An IP allowlist limits a key to requests from your servers’ IP addresses. A request from any other address gets 403 api_key_ip_blocked, even with the correct key.

• Enter IP addresses (IPv4 or IPv6), separated by commas or spaces. You can also enter a range in CIDR notation, for example 203.0.113.0/24.
• Leave the field empty to allow requests from any IP address.
• The address that counts is your server’s public address, the one SanadWA sees. If your servers reach the internet through a NAT gateway or a proxy, use that address.

You cannot edit the allowlist of an existing key. To change it, create a new key with the new list, move your systems to the new key, then revoke the old key.

We recommend an allowlist for every key used in production.

Rotate a key

Rotating replaces a key with a new one that has the same name, scope, IP allowlist and rate limit.

1. In Settings → Developers → API keys, click Rotate next to the key.
2. Copy the new key. It is shown only once.

The old key stops working immediately

Rotation revokes the old key at the same moment the new key is created. There is no overlap. Requests that use the old key fail with 401 api_key_invalid until your systems use the new key.

To change keys without any failed requests, create a second key instead of rotating:

1. Create a new key with the same scope and allowlist.
2. Deploy the new key to your systems.
3. Check in the console (Last used column) that the old key is no longer used.
4. Revoke the old key.

Revoke a key

Click Revoke next to the key. Revoking cannot be undone. Every request with that key fails with 401 api_key_invalid from that moment.

Revoke a key at once if you think someone else has seen it.

Keep your keys secret

An API key can send WhatsApp messages from your business number, and those messages cost you money. Treat it like a password.

• Use the key only on your server. Never put it in a website, a browser extension, a mobile app or any other code that runs on your customers’ devices. Anyone can read keys from that code. The SanadWA API does not accept calls from web browsers on other websites.
• Keep the key in an environment variable or a secret manager, not in source code.
• Never commit a key to Git, and never paste it into a chat, ticket or email.
• Use a separate key for each system and environment, so that you can revoke one without the others.
• Add an IP allowlist.
• If a key leaks, revoke it and create a new one.