Create, scope and revoke API keys safely

Manage up to 5 API keys per account with agent scoping, server-side storage, and webhook notifications for key creation and revocation.

Short answer. Create up to 5 API keys in your Speakvora dashboard, scope them to individual agents for restricted access, keep them on a server (not in browsers), and revoke them anytime. Webhooks notify you when keys are created or revoked.

Key limits and creation

Each Speakvora account can create up to 5 API keys. Generate new keys in your dashboard whenever you need a fresh credential for a new application, environment, or team member. Each key is a unique token used to authenticate requests to the Speakvora API.

Agent-scoped keys for restricted access

When you publish a voice agent from the Agent builder, you can generate an agent-scoped API key. This key reaches only that specific agent and cannot access other agents, voices, or account settings.

Agent-scoped keys are ideal for sharing access with third parties or deploying agents in untrusted environments. A scoped key can only call POST /v1/agents/{agent_id}/turn and POST /v1/agents/{id}/sessions (for browser tokens). Plain /v1/speak requests reject scoped keys, so text-to-speech from a browser needs your backend to call the API with a full account key.

Keep keys on a server

Store all API keys on a backend server, never in client-side code, browser local storage, or mobile apps. If a key is exposed in a public repository or client code, revoke it immediately from the dashboard.

For browser-based agents, use a server endpoint to exchange a short-lived session token. Call POST /v1/agents/{id}/sessions with your account key to get a 10-minute browser token, then pass that token to the client. Browser tokens are scoped to one agent and expire quickly.

Revoke keys anytime

Revoke a key from the dashboard whenever you no longer need it, rotate credentials, or suspect a key has been compromised. Revocation is immediate; any request using that key will fail with an authentication error.

Webhook notifications

Speakvora sends webhooks for key lifecycle events. Set up webhook endpoints in your dashboard to receive notifications when keys are created or revoked.

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

Event: test.ping — test your webhook endpoint
Event: key.created — a new key was generated
Event: key.revoked — a key was deleted

Authentication headers

Send your API key in the x-api-key header or as a Bearer token in the Authorization header. Both formats are accepted:

API key authentication

# Using x-api-key header
curl -H "x-api-key: YOUR_KEY" https://speakvora.com/api/v1/voices

# Using Authorization Bearer token
curl -H "Authorization: Bearer YOUR_KEY" https://speakvora.com/api/v1/voices

Frequently asked questions

Can I use the same key in multiple applications?

Yes, but it is safer to create separate keys for each application or environment. That way you can revoke one key without affecting others. Agent-scoped keys are even more restricted and can only access a single agent.

What happens if I revoke a key?

Any request using that key will fail immediately with an authentication error. Revocation is instant and cannot be undone; you must create a new key if you need access again.

How do I authenticate from a browser?

Do not put API keys in browser code. Instead, call POST /v1/agents/{id}/sessions from your backend with your account key to get a 10-minute session token. Pass that token to the browser in the Authorization header. Session tokens are scoped to one agent and expire automatically.

What is the difference between a full key and an agent-scoped key?

A full account key can access all agents, voices, and account features. An agent-scoped key can only reach one specific agent via POST /v1/agents/{agent_id}/turn and POST /v1/agents/{id}/sessions. Use scoped keys to limit exposure when sharing access.

How do I verify webhook signatures?

Compute HMAC-SHA256(secret, timestamp + "." + rawBody) and compare it to the x-speakvora-signature header. Also check that x-speakvora-timestamp is not older than 5 minutes. Reject any webhook that fails either check.