API Keys

Manage API keys for programmatic access to Voxvaani’s platform APIs. API keys authenticate requests to WhatsApp messaging, email dispatch, and balance query endpoints.

Overview

Each API key is scoped to specific permissions, allowing you to grant only the access your application needs. Keys can be created, viewed (metadata only), revoked, and deleted from the API Keys management page.

API Key Permissions Reference

Choosing the Right Scopes

Creating Your First Key

1. Navigate to Settings from the sidebar and go to the API Keys section.
2. Click Create New Key.
3. Enter a descriptive Key Name that identifies its purpose (e.g., “Production WhatsApp Bot” or “Staging Email Integration”).
4. Select the scopes the key should have. Start with only what your integration needs.
5. Click Create.
6. Copy the key immediately — see warning below.

Testing Your New Key

After creating a key, verify it works before integrating it into your application:

CURL:

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

Expected response (HTTP 200):

{
  "success": true,
  "voiceMins": 250,
  "whatsappBalance": 1000,
  "emailBalance": 1000,
  "leadBalance": 100
}

If you receive a 401, the key is invalid or was not copied correctly. If you receive a 403, the key lacks the balance:read scope.

Managing Keys

Key Rotation Checklist

Follow these steps to rotate a key without downtime:

1. Create a replacement key with identical scopes.
2. Deploy the new key to your application — update environment variables, secrets manager, or configuration files.
3. Verify the new key works — make a test API call and confirm a 200 response.
4. Revoke the old key from the API Keys settings page.
5. Confirm revocation — verify the old key now returns 401.

Rotate keys every 90 days for production environments. Rotate immediately if a key is suspected to be compromised, or if a team member with access to the key leaves the organization.

Environment Strategy

Use separate API keys for each stage of your development lifecycle:

This separation ensures:

• A bug in development code cannot affect production data.
• Staging can be tested with production-equivalent permissions without risking live balances.
• Compromised development keys have zero impact on production systems.

Webhook Endpoint Management

Voxvaani supports webhook endpoints for receiving real-time event notifications:

To configure webhooks:

1. Navigate to Settings from the sidebar and go to the API Keys section.
2. Click the Webhooks tab.
3. Enter your endpoint URL (must be HTTPS).
4. Set a verification token — this token is used to validate that incoming webhook requests originate from Voxvaani.
5. Select which events you want to receive.
6. Click Save.

Security Best Practices

Related Articles

• API Reference Overview
• Authentication
• WhatsApp API