Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
API Keys

All API requests require authentication using a Bearer token in the Authorization header. 
Authorization: Bearer zv_live_xxxxxxxxxxxxxxxxxxxxxxxx

​
Key Types

PrefixEnvironmentUsage
zv_live_ProductionReal messages, real costs
zv_test_SandboxTesting without sending real messages
Test keys (zv_test_) simulate message sending but don’t actually deliver messages. Use them for development and testing.

​
Creating API Keys

  1. Log in to your Zavu Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Give it a descriptive name (e.g., “Production Server”, “Development”)
  5. Copy and securely store the key
API keys are only shown once at creation. If you lose a key, you’ll need to create a new one.

​
Using API Keys

​
In HTTP Requests

Include the key in the Authorization header: 
curl https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer zv_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

​
In SDKs

import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'], // This is the default and can be omitted
});

​
Optional Headers

HeaderDescriptionExample
Zavu-SenderOverride the default sendersnd_abc123
Idempotency-KeyPrevent duplicate sendsorder-12345-confirmation

​
Zavu-Sender Header

Override the default sender for a specific request: 
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Zavu-Sender: snd_abc123" \
  -H "Content-Type: application/json" \
  -d '{"to": "+56912345678", "text": "Hello!"}'

​
Idempotency Keys

Prevent duplicate message sends due to network retries: 
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+56912345678",
    "text": "Your order #12345 has shipped!",
    "idempotencyKey": "order-12345-shipped"
  }'
If you retry this request with the same idempotencyKey, you’ll receive a 409 Conflict with the original message instead of sending a duplicate.

​
Security Best Practices

Never expose your API keys in client-side code, public repositories, or browser applications.

​
Do’s

  • Store keys in environment variables
  • Use different keys for development and production
  • Rotate keys periodically (every 90 days recommended)
  • Use the minimum permissions needed
  • Monitor key usage in your dashboard

​
Don’ts

  • Don’t commit keys to version control
  • Don’t share keys via email or chat
  • Don’t use production keys in development
  • Don’t embed keys in mobile apps or frontends

​
Frontend Integration

The Zavu API uses secret API keys that must never be exposed in client-side code. If you include your key in a browser app, anyone can open DevTools and steal it. Instead, use the Backend-for-Frontend (BFF) pattern: your frontend calls your own server endpoint, and your server calls the Zavu API.

​
Server-side proxy examples

// app/api/send-message/route.ts
import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev(); // reads ZAVUDEV_API_KEY from env

export async function POST(request: Request) {
  const { to, text } = await request.json();

  const result = await zavu.messages.send({ to, text });
  return Response.json(result);
}

​
Frontend example

React
async function sendMessage(to: string, text: string) {
  const res = await fetch('/api/send-message', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ to, text }),
  });
  return res.json();
}
Add your own authentication and validation to the proxy endpoint. The examples above are simplified for clarity.

​
Key Permissions

API keys can be scoped to specific permissions:
PermissionDescription
*Full access to all resources
messages:sendSend messages
messages:readRead message status and history
templates:readRead templates
templates:writeCreate and update templates
contacts:readRead contact information
contacts:writeCreate and update contacts

​
Revoking Keys

If a key is compromised:
  1. Go to Settings → API Keys
  2. Find the compromised key
  3. Click Revoke
  4. Create a new key
  5. Update your applications
Revoked keys are immediately invalidated and cannot be restored.

​
Error Responses

StatusErrorDescription
401unauthorizedMissing or invalid API key
403forbiddenKey lacks required permissions
429rate_limit_exceededToo many requests
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}