Authentication
Authenticate KugelAudio API requests with an API key over HTTP, WebSocket and the SDKs, and create, scope, revoke and troubleshoot your keys.
On this page
Protected API requests require authentication using an API key. The health and model-catalog endpoints are public; synthesis, voice, and dictionary endpoints authenticate the caller. This page explains how to obtain and use your API key.
Getting Your API Key
- Sign up at kugelaudio.com. New accounts start with free Text to Speech credit, no credit card needed.
- Go to your Dashboard
- In the sidebar, open Team & Settings → API Keys
- Click Create key and give it a descriptive name (for example, "Production Server")
- Choose when it expires and what it may do (see Key permissions)
- Copy and securely store your key
Using Your API Key
HTTP Requests
Include your API key in the Authorization header using Bearer token format:
curl -X POST "https://api.kugelaudio.com/v1/tts/generate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Hello, world!", "model_id": "kugel-3.5", "voice_id": 1071}'The native API also accepts the equivalent X-API-Key header:
curl "https://api.kugelaudio.com/v1/voices?limit=1" \
-H "X-API-Key: YOUR_API_KEY"The api_key query parameter is also accepted, but use a header for HTTP
requests so the secret is less likely to appear in URLs and access logs.
WebSocket Connections
WebSocket connections accept the same credentials. Pass Authorization: Bearer
or X-API-Key in the handshake headers when your client library supports
custom headers:
import asyncio
import os
import websockets
async def main():
async with websockets.connect(
"wss://api.kugelaudio.com/ws/tts",
additional_headers={"Authorization": f"Bearer {os.environ['KUGELAUDIO_API_KEY']}"},
) as ws:
pass # send TTS messages; see the WebSocket reference
asyncio.run(main())Server-side clients that cannot set handshake headers can use the query form:
// Node.js, using the `ws` package
import WebSocket from 'ws';
const ws = new WebSocket(
`wss://api.kugelaudio.com/ws/tts?api_key=${process.env.KUGELAUDIO_API_KEY}`,
);Never open these connections from browser code: the key would be visible to anyone using the page. Proxy browser traffic through your own server.
SDK Usage
from kugelaudio import KugelAudio
import os
# Pass directly
client = KugelAudio(api_key="YOUR_API_KEY")
# Or read the environment variable explicitly
client = KugelAudio(api_key=os.environ["KUGELAUDIO_API_KEY"])import { KugelAudio } from 'kugelaudio';
// Read the key from the environment (Node.js)
const client = new KugelAudio({ apiKey: process.env.KUGELAUDIO_API_KEY! });# Set your API key as an environment variable
export KUGELAUDIO_API_KEY="YOUR_API_KEY"
# Then reference it in requests
curl "https://api.kugelaudio.com/v1/voices?limit=1" \
-H "Authorization: Bearer $KUGELAUDIO_API_KEY"Environment Variables
For security, we recommend using environment variables instead of hardcoding API keys:
# .env file
KUGELAUDIO_API_KEY=your_api_key_hereThe Python and JavaScript clients require the key in their constructors; read
KUGELAUDIO_API_KEY from your process environment as shown above. The Java
client also provides KugelAudio.fromEnv().
Traffic goes to the canonical geo-routed endpoint by default; see
Regions to pin traffic to the EU endpoint.
API Key Security
Never expose keys in client-side code
API keys should only be used in server-side code. Never include them in:
- Frontend JavaScript
- Mobile app source code
- Public repositories
- Client-side environment variables
Rotate keys regularly
Create new API keys periodically and delete old ones. This limits the impact of any potential key exposure.
Use separate keys for environments
Create separate API keys for development, staging, and production. This makes it easier to rotate keys and track usage.
Managing API Keys
Create keys as described in Getting Your API Key.
Editing keys
Hover a key in Team & Settings → API Keys and click the pencil to change its name, expiration or permissions. The secret stays the same, so nothing needs to be redeployed. Expired and revoked keys cannot be edited; create a new key instead.
Revoking keys
If a key is compromised:
- Create a new key and update your applications
- In Team & Settings → API Keys, click the trash icon on the old key and confirm Revoke key
A revoked key cannot be restored. It stays in the list with the status Revoked, and its usage history stays on the Usage page.
Key scope
Dashboard API keys are scoped to a project. Resource APIs such as dictionaries enforce that project scope.
Key permissions
Each key also has permissions, chosen when you create it and changeable later:
| Setting | What the key can do |
|---|---|
| All | Everything, including resources added in the future. Keys created before permissions existed have this setting. |
| Read only | List and read voices and dictionaries. It cannot generate audio and cannot change anything. |
| Restricted | Exactly the resources you allow, each set to None, Read or Write (or Allowed for resources that have no read access). |
| Resource | Levels | Covers |
|---|---|---|
| Text to speech | None, Allowed | Speech generation over HTTP and WebSocket, including the ElevenLabs, Vapi, Cognigy and Azure compatible endpoints |
| Realtime sessions | None, Allowed | Realtime voice sessions. Not yet available on the public API |
| Speech enhancement | None, Allowed | Speech enhancement |
| Voices | None, Read, Write | Read lists and inspects voices. Write also clones, edits, publishes and deletes them |
| Dictionaries | None, Read, Write | Read lists dictionaries and their entries. Write also creates, edits and deletes them |
| Organization projects | None, Read, Write | Read lists the organization's projects. Write also creates and deletes projects and issues and revokes their API keys |
Speech to text (None, Allowed) covers transcription, as a file or as a stream. A read-only key cannot transcribe.
Realtime sessions (None, Allowed) covers speech to speech.
Write includes read. Generating speech with a voice or a dictionary needs only
Text to speech, not read access to voices or dictionaries, and a key allowed
Text to speech may also read a single voice by id (GET /v1/voices/{voice_id}). A restricted key
never gains access to a resource added later, and the on-prem licensing endpoints
accept only keys set to All.
Organization projects is never part of All: grant it explicitly on a Restricted key. Only organization owners and admins can grant it, and the key works only while the person who created it is still an owner or admin. See Projects.
Authentication Errors
401 Unauthorized
{
"error": "Invalid API key",
"error_code": "UNAUTHORIZED",
"code": 401
}When the request carries no credentials at all, error reads
"No credentials provided. Use ?api_key=, X-API-Key, or Authorization: Bearer."
Causes:
- No credentials in the request
- Invalid or deleted API key
- Malformed header format
Solutions:
- Send the key as
Authorization: Bearer YOUR_API_KEY,X-API-Key: YOUR_API_KEY, or theapi_keyquery parameter - Verify the API key is correct and has not been deleted
- For the EU endpoint, send the key without the
eu-prefix (only the SDKs strip it; see Regions)
403 Forbidden
{
"error": "Forbidden",
"error_code": "UNAUTHORIZED",
"code": 403
}Causes:
- Trying to access resources from another account
- Using a key whose project does not own the requested resource
- Calling voice-management operations with a credential that has no organization/user identity
Solutions:
- Verify you're using the correct API key
- Verify the key belongs to the resource's project or organization
A key that is valid but lacks the permission for the endpoint gets a distinct code:
{
"error": "This API key does not have the voices:write permission",
"error_code": "PERMISSION_DENIED",
"code": 403
}Grant the named permission on the key (see Key permissions) or use a key that has it.
Testing Authentication
Verify your API key is working:
curl --fail-with-body "https://api.kugelaudio.com/v1/voices?limit=1" \
-H "Authorization: Bearer YOUR_API_KEY"A valid key receives a 200 voice-page response. A missing, invalid, or deleted
key receives the standard 401 UNAUTHORIZED error envelope. Do not use
/v1/models for this check: the model catalog is public and cannot verify a key.