API Key Authentication
Every request to the omnichannel API must include your API key. Keys are issued per account from System → Developer → API Key (also Profile → API Key). Send the key on the apikey HTTP header (or apiKey / body apikey). Portal walkthrough: Account → API keys.
Treat the API key like a password. Do not commit it to source control, put it in a mobile app, or paste it into a public ticket. If it leaks, rotate it in the dashboard before you continue sending.
What an API key is
The key identifies your account, not a logged-in portal user. Portal screens use a login session. HTTP send uses this key.
| Use | Auth |
|---|---|
| Portal compose, inbox, fallback, CDP | Sign in |
POST /v1/sms, /v1/whatsapp, /v1/rcs, /v1/verify | apikey header |
| Public CDP form / inbound webhook | Form or webhook slug — not this key |
One account can have several keys (for example staging vs production). Inactive users or keys are rejected.
Create a key
- Open System → Developer → API Key, or Profile → API Key. See Account.
- Generate API Key and give it a title you will recognise later.
- Copy the key once. Store it in your server environment (
AZMARQ_API_KEYif you use the SDK). - Optional: set an IP allowlist and priority (below).
You need wallet credits and an approved sender / template / bot before the first send. The key alone is not enough. Quickstart walks the first SMS.
How to send it
Prefer the header. Body apikey is accepted on many send endpoints so older clients still work.
| Place | Name |
|---|---|
| Header (preferred) | apikey or apiKey |
| JSON body or query | apikey |
Do not send Authorization: Bearer … as a substitute. Some MCP hosts only emit Bearer; Omni still expects apikey (or x-api-key on the public MCP HTTP bind).
Headers
- Name
apikey- Type
- string
- Description
Your dashboard API key. Required on every request.
- Name
Content-Type- Type
- string
- Description
Use
application/jsonfor JSON bodies. Usemultipart/form-dataonly when an endpoint uploads a file, such as WhatsApp header media.
Base URL
The HTTP API host is https://api.azmarq.com. Each endpoint page prints the full URL, such as https://api.azmarq.com/v1/sms. In examples, $API_BASE_URL is https://api.azmarq.com — copy the path from the endpoint bar on the same page. Do not invent a hostname.
IP allowlist and priority
| Setting | What it does |
|---|---|
| IP allowlist | Only those server IPs can call the APIs with this key. Empty means any IP (still keep the key secret). |
| Priority | Queue priority for sends on a busy account |
If you set an allowlist and then call from a laptop or CI IP that is not listed, the send fails even with a valid key. Add the egress IP of the environment that actually posts.
Rotate and disable
- Rotate when a key may have leaked, a teammate left, or you split staging from production.
- Disable / delete keys you no longer use.
- After rotate, update the server env and any Postman
apiKeyvariable.
Disabling a key does not log you out of the portal.
Example
Authenticated request
curl -X POST "https://api.azmarq.com/v1/sms" \
-H "Content-Type: application/json" \
-H "apikey: YOUR_API_KEY" \
-d '{
"sender": "senderName",
"to": "91XXXXXXXXXX",
"text": "Hello World!",
"type": "TRANSACTIONAL"
}'
A missing or unknown key returns:
Error response
{
"error": true,
"message": "Api Key not found"
}
The Omni SDK (azmarqomni) and Omni MCP (azmarqomni-mcp) use this same key. The SDK reads AZMARQ_API_KEY and sends apikey. MCP stdio does the same. A public MCP HTTP bind ignores the process env key and requires apikey (or x-api-key) on each request.
Typical mistakes
| Situation | What to do |
|---|---|
Api Key not found | Header name is apikey, no extra quotes, key still active |
| Works in Postman, fails in production | IP allowlist missing the server egress IP |
| Portal works, HTTP fails | Portal login is not the API key — create a developer key |
| Key in a website widget | Widgets do not use apikey. See Get Widgets |
| 401-style Bearer setup | Use the apikey header |
See Errors for how to read unsuccessful responses, then Quickstart to send your first message.