Skip to main content

​
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 { Zavu } from '@zavu/node';

const zavu = new Zavu(process.env.ZAVU_API_KEY);

​
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

​
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"
  }
}