API Authentication

Agency plan required

All BuildVoiceAI API requests require authentication using an API key. This page covers how to generate keys, use them in requests, and follow security best practices.

Generating an API Key

Navigate to Integrations in the sidebar
Find the API & Webhooks card and click Connect (or Manage if already set up)
Click Generate API Key
Copy the key immediately and store it securely

API key generation page in Settings showing the generated key

⚠️

Your API key is displayed only once at the time of generation. If you lose it, you must generate a new one. Generating a new key immediately invalidates the previous key.

Using the API Key

Include your API key in the Authorization header of every request using the Bearer token format:


Authorization: Bearer bvai_sk_1a2b3c4d5e6f7g8h9i0j

Example Request


curl -X POST https://app.buildvoiceai.com/api/v1/calls/trigger \
  -H "Authorization: Bearer bvai_sk_1a2b3c4d5e6f7g8h9i0j" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+15551234567", "agent_id": "your-agent-uuid"}'

API Key Format

BuildVoiceAI API keys use the prefix bvai_sk_ followed by a random string. If your key does not start with this prefix, it may be invalid or from a different service.

Rate Limits

API requests are rate-limited to prevent abuse and ensure platform stability:

Limit	Value
Requests per minute	100
Concurrent calls per key	10

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait:


{
  "success": false,
  "error": "Rate limit exceeded. Retry after 12 seconds."
}

💡

If you consistently hit rate limits, implement exponential backoff in your integration. Space out bulk call triggers rather than sending them all at once.

Enabling and Disabling API Access

You can toggle API access without deleting your key:

Go to Integrations → API & Webhooks
Toggle the Enable/Disable switch

When disabled, all API requests return 403 Forbidden. Your key is preserved and will work again when re-enabled.

Key Rotation

Regularly rotating your API key is a security best practice. To rotate:

Generate a new API key (this invalidates the old one immediately)
Update all systems that use the old key
Verify your integrations are working with the new key

⚠️

Key rotation is immediate. The old key stops working the moment a new one is generated. Plan your rotation during a low-traffic window to avoid disrupting live integrations.

Security Best Practices

Do

Store API keys in environment variables, not in source code
Use server-side requests only — never expose keys in client-side JavaScript
Rotate keys periodically (every 90 days is recommended)
Monitor your API usage for unexpected patterns
Disable API access when not actively using it

Do Not

Commit API keys to version control (Git, SVN, etc.)
Share keys via email, Slack, or other messaging platforms
Use the same key across multiple environments (use separate keys for staging and production)
Include keys in URL parameters