Authentication

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
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

API keys are shown only once when created. Store them securely! If you lose a key, you’ll need to create a new one.

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

Python
JavaScript
cURL

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_here

The 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.

API-key lookups are cached briefly. A revocation, an expiration change or a permission change can take roughly 30 seconds, and in rare cases a few minutes, to reach every server. Rotate applications before revoking the old key and do not rely on revocation as an instantaneous session kill.

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

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 the api_key query 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.

Get started

Build a voice agent

Generate audio

Voices

Enhance audio

Hosting and deployment

SDK Reference

API Reference

Getting Your API Key

Using Your API Key

HTTP Requests

WebSocket Connections

SDK Usage

Environment Variables

API Key Security

Managing API Keys

Editing keys

Revoking keys

Key scope

Key permissions

Authentication Errors

401 Unauthorized

403 Forbidden

Testing Authentication

Next steps

Quick Start

Errors

​Getting Your API Key

​Using Your API Key

​HTTP Requests

​WebSocket Connections

​SDK Usage

​Environment Variables

​API Key Security

​Managing API Keys

​Editing keys

​Revoking keys

​Key scope

​Key permissions

​Authentication Errors

​401 Unauthorized

​403 Forbidden

​Testing Authentication

​Next steps

Quick Start

Errors

Getting Your API Key

Using Your API Key

HTTP Requests

WebSocket Connections

SDK Usage

Environment Variables

API Key Security

Managing API Keys

Editing keys

Revoking keys

Key scope

Key permissions

Authentication Errors

401 Unauthorized

403 Forbidden

Testing Authentication

Next steps