API Keys and Scoped Access

Manage up to 5 API keys per account. Scoped keys restrict access to a single agent. Learn authentication, key limits, and webhook events.

Short answer. You can create up to 5 API keys per account. Agent-scoped keys reach only their assigned agent, while full-access keys work across all endpoints. Keep keys on a server and use the x-api-key header or Bearer token for authentication.

Key Limits and Types

Each account can have up to 5 active API keys. You create and manage them in the portal at https://speakvora.com/dashboard.

Full-access keys work across all Speakvora endpoints: text-to-speech, speech-to-text, voice agents, packs, and voice management.

Agent-scoped keys are restricted to a single voice agent. When you generate an API for an agent in the Agent builder, you receive an agent-scoped key that works only for that agent's endpoint. This is useful for limiting exposure if a key is compromised.

Authentication

Send your API key in the x-api-key header or as a Bearer token in the Authorization header. Always keep keys on a server; do not embed them in client-side code.

Example: Authenticate with x-api-key

curl -X POST https://speakvora.com/api/v1/speak \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "voice": "af_heart", "lang": "en"}'

Agent-Scoped Keys

When you publish an agent version in the Agent builder, the "Generate API" button creates an agent-scoped key. This key is shown once and cannot be retrieved later.

An agent-scoped key can only reach its assigned agent's turn endpoint. It cannot access text-to-speech, speech-to-text, voice browsing, or other agents.

For browser-based agents, use a 10-minute session token instead of a key. Request a session token from your backend using the agent-scoped key, then pass the token to the browser.

Key Events and Webhooks

Speakvora sends webhook events when keys are created or revoked. Set up webhooks in the portal under Webhooks.

Webhook events include test.ping (for testing your endpoint), key.created, and key.revoked. Each webhook includes a timestamp and an HMAC-SHA256 signature in the x-speakvora-signature header. Reject webhooks older than 5 minutes.

Rate Limits

Rate limits are per account, not per key. The POST /v1/prepare endpoint has a daily limit per account; requests over the limit receive a 429 reply with the error live_rate_limited.

Security Best Practices

Keep keys on a server; never expose them in client-side code or version control
Use agent-scoped keys for agent endpoints to limit the scope of a compromised key
Rotate keys regularly and revoke unused ones in the portal
Monitor webhook events for key.created and key.revoked to detect unauthorized changes

Frequently asked questions

How many API keys can I create?

You can have up to 5 active API keys per account. Create and manage them in the dashboard.

What can an agent-scoped key do?

An agent-scoped key can only reach its assigned agent's turn endpoint. It cannot access text-to-speech, speech-to-text, or other agents. Use it to safely expose a single agent to a third party.

How do I authenticate API requests?

Send your API key in the x-api-key header or as a Bearer token in the Authorization header. Always keep keys on a server.

What webhook events does Speakvora send?

Speakvora sends test.ping (for testing), key.created, and key.revoked events. Each includes a timestamp and HMAC-SHA256 signature. Reject webhooks older than 5 minutes.

Can I use an API key in a browser?

No. For browser-based agents, request a 10-minute session token from your backend using the agent-scoped key, then pass the token to the browser.