Authentication

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

Log in to your Zavu Dashboard
Navigate to Settings → API Keys
Click Create API Key
Give it a descriptive name (e.g., “Production Server”, “Development”)
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
});

import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),  # This is the default and can be omitted
)

require "zavudev"

client = Zavudev::Client.new(api_key: ENV["ZAVUDEV_API_KEY"])

import (
	"os"
	"github.com/zavudev/sdk-go"
	"github.com/zavudev/sdk-go/option"
)

client := zavudev.NewClient(option.WithAPIKey(os.Getenv("ZAVUDEV_API_KEY")))

<?php
$client = new Zavudev\Client(apiKey: getenv('ZAVUDEV_API_KEY'));

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": "+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);
}

import express from 'express';
import Zavudev from '@zavudev/sdk';

const app = express();
app.use(express.json());

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

app.post('/api/send-message', async (req, res) => {
  const { to, text } = req.body;

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

from fastapi import FastAPI
from pydantic import BaseModel
from zavudev import Zavudev

app = FastAPI()
zavu = Zavudev()  # reads ZAVUDEV_API_KEY from env

class MessageRequest(BaseModel):
    to: str
    text: str

@app.post("/api/send-message")
async def send_message(req: MessageRequest):
    result = zavu.messages.send(to=req.to, text=req.text)
    return result

require "sinatra"
require "sinatra/json"
require "zavudev"

client = Zavudev::Client.new # reads ZAVUDEV_API_KEY from env

post "/api/send-message" do
  body = JSON.parse(request.body.read)
  result = client.messages.send(to: body["to"], text: body["text"])
  json result
end

package main

import (
	"encoding/json"
	"net/http"

	"github.com/zavudev/sdk-go"
	"github.com/zavudev/sdk-go/option"
)

var client = zavudev.NewClient() // reads ZAVUDEV_API_KEY from env

func sendMessage(w http.ResponseWriter, r *http.Request) {
	var req struct {
		To   string `json:"to"`
		Text string `json:"text"`
	}
	json.NewDecoder(r.Body).Decode(&req)

	result, _ := client.Messages.Send(r.Context(), zavudev.MessageSendParams{
		To:   zavudev.String(req.To),
		Text: zavudev.String(req.Text),
	})
	json.NewEncoder(w).Encode(result)
}

func main() {
	http.HandleFunc("/api/send-message", sendMessage)
	http.ListenAndServe(":3000", nil)
}

<?php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

$client = new Zavudev\Client(); // reads ZAVUDEV_API_KEY from env

Route::post('/api/send-message', function (Request $request) use ($client) {
    $result = $client->messages->send([
        'to' => $request->input('to'),
        'text' => $request->input('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:

Go to Settings → API Keys
Find the compromised key
Click Revoke
Create a new key
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"
  }
}

​API Keys

​Key Types

​Creating API Keys

​Using API Keys

​In HTTP Requests

​In SDKs

​Optional Headers

​Zavu-Sender Header

​Idempotency Keys

​Security Best Practices

​Do’s

​Don’ts

​Frontend Integration

​Server-side proxy examples

​Frontend example

​Key Permissions

​Revoking Keys

​Error Responses

API Keys

Key Types

Creating API Keys

Using API Keys

In HTTP Requests

In SDKs

Optional Headers

Zavu-Sender Header

Idempotency Keys

Security Best Practices

Do’s

Don’ts

Frontend Integration

Server-side proxy examples

Frontend example

Key Permissions

Revoking Keys

Error Responses