Authentication

All TryVox API requests require authentication using API keys passed via the Authorization header.

API Keys

API keys are created and managed in the TryVox Dashboard. Each key is scoped to your account and grants full access to your resources.

Key Formats

TryVox uses different key prefixes for different environments:

• Production keys: tvx_sk_live_...
• Sandbox keys: tvx_sk_test_...

Always use production keys for live traffic and sandbox keys for development and testing.

Making Authenticated Requests

Include your API key in the Authorization header using the Bearer token scheme:

curl https://api.tryvox.io/v1/voice/accounts/{auth_id}/calls \
  -H "Authorization: Bearer tvx_sk_live_abc123xyz..."

Authorization Header Format

Authorization: Bearer <api_key>

Replace <api_key> with your actual API key from the dashboard.

Account-Scoped Endpoints

Many TryVox endpoints are account-scoped and require the account ID in the URL path:

https://api.tryvox.io/v1/voice/accounts/{auth_id}/calls

Replace {auth_id} with your account ID, which you can find in the dashboard.

Example: Making a Call

curl -X POST https://api.tryvox.io/v1/voice/accounts/AC123456/calls \
  -H "Authorization: Bearer tvx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+919876543210",
    "to": "+14155551234",
    "answer_url": "https://your-app.com/answer"
  }'

Tenant-Scoped Operations

For multi-tenant applications, TryVox also accepts an optional X-Tenant-ID header for tenant-scoped operations:

curl https://api.tryvox.io/v1/voice/accounts/{auth_id}/calls \
  -H "Authorization: Bearer tvx_sk_live_abc123..." \
  -H "X-Tenant-ID: tenant_xyz"

This header is useful when you need to isolate resources or track usage per tenant.

Security Best Practices

Keep Keys Secret

• Never commit API keys to version control (git, etc.)
• Never expose keys in client-side code (JavaScript, mobile apps)
• Use environment variables to store keys in your application

Rotate Keys Regularly

Rotate your API keys periodically to minimize the impact of a potential compromise:

1. Create a new API key in the dashboard
2. Update your application to use the new key
3. Delete the old key once the migration is complete

Monitor Key Usage

The TryVox dashboard shows API usage per key. Monitor for:

• Unexpected spikes in traffic
• Requests from unfamiliar IP addresses
• Unusual error rates

If you suspect a key has been compromised, delete it immediately and create a new one.

Testing Authentication

You can test your authentication by making a simple API call:

curl https://api.tryvox.io/v1/account/{account_id}/numbers \
  -H "Authorization: Bearer tvx_sk_live_abc123..."

Success (200 OK):

{
  "data": [
    {
      "e164": "+919876543210",
      "country": "IN",
      "status": "active"
    }
  ]
}

Failure (401 Unauthorized):

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Next Steps

• Make your first call
• Understand error responses
• Set up webhooks