Authentication

Secure your API requests with Bearer tokens

API Keys

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

Authorization: Bearer zv_live_xxxxxxxxxxxxxxxxxxxxxxxx

Key Types

Prefix	Environment	Usage
zv_live_	Production	Real messages, real costs
zv_test_	Sandbox	Testing 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

TypeScript

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

Header	Description	Example
Zavu-Sender	Override the default sender	snd_abc123
Idempotency-Key	Prevent duplicate sends	order-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": "[phone]", "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": "[phone]",
    "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

Next.js (App Router)

// 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:

Permission	Description
*	Full access to all resources
messages:send	Send messages
messages:read	Read message status and history
templates:read	Read templates
templates:write	Create and update templates
contacts:read	Read contact information
contacts:write	Create 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

Status	Error	Description
401	unauthorized	Missing or invalid API key
403	forbidden	Key lacks required permissions
429	rate_limit_exceeded	Too many requests

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}