API Authentication

All Voxvaani API requests require authentication using an API key.

Quick Auth Summary

Authentication Methods

Include your API key using one of these methods:

Recommended — x-api-key header:

x-api-key: YOUR_API_KEY

Alternative — Authorization Bearer header:

Authorization: Bearer YOUR_API_KEY

Also supported — Authorization ApiKey header:

Authorization: ApiKey YOUR_API_KEY

All three methods are functionally equivalent. x-api-key is recommended because it keeps keys separate from OAuth/SSO tokens that may also use the Authorization header.

Permission Scopes

API keys support granular permissions. When creating a key, assign only the scopes your integration actually needs. Each scope unlocks a specific set of endpoints:

Principle of least privilege: If your app only checks balances, do not grant it whatsapp:send. If your app sends bulk messages, it needs whatsapp:bulk-send but may not need whatsapp:send or email:send. Each unnecessary scope increases the blast radius of a compromised key.

Obtaining an API Key

1. Log in to your Voxvaani account.
2. Navigate to Settings from the sidebar and go to the API Keys section.
3. Click Create New Key.
4. Enter a descriptive name (e.g., “Production WhatsApp Bot”).
5. Select the required permission scopes.
6. Click Create and copy the key immediately — it is shown only once.

Example Requests

CURL

curl -X GET "https://voxvaani.com/api/v1/balance" \
  -H "x-api-key: YOUR_API_KEY"

Python

import requests
 
headers = {"x-api-key": "YOUR_API_KEY"}
 
response = requests.get(
    "https://voxvaani.com/api/v1/balance",
    headers=headers
)
print(response.json())

JavaScript (Node.js)

const response = await fetch("https://voxvaani.com/api/v1/balance", {
  headers: { "x-api-key": "YOUR_API_KEY" }
});
const data = await response.json();
console.log(data);

JavaScript (Browser)

// WARNING: Never expose API keys in client-side code.
// Route API calls through your backend server instead.

Multi-Key Strategy

For applications with multiple environments or services, use separate API keys:

Benefits of separate keys:

• If one key is compromised, only that service is affected.
• You can revoke and rotate individual keys without disrupting other services.
• Transaction logs show which service made each API call, simplifying audit and debugging.

API Key Security Checklist

Key Rotation Workflow

1. Create a new key with the same scopes while the old key is still active.
2. Deploy the new key to your application (update environment variable or secrets manager).
3. Verify the application works with the new key — check a few API calls return 200.
4. Revoke the old key from the API Keys settings page.
5. Confirm the old key returns 401 — verify revocation took effect.

Error Responses

Every error response is a single error field containing a descriptive message.

Authentication failure (missing or invalid key — HTTP 401):

{
  "error": "Unauthorized: Invalid or missing API key"
}

Insufficient scope (valid key, wrong permissions — HTTP 403):

{
  "error": "Forbidden: This API key does not have the 'whatsapp:send' permission."
}

Related Articles

• Settings 
• API Reference Overview
• WhatsApp API