Skip to content
KugelAudioDocs

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

  1. Sign up at kugelaudio.com. New accounts start with free Text to Speech credit, no credit card needed.
  2. Go to your Dashboard
  3. In the sidebar, open Team & Settings → API Keys
  4. Click Create key and give it a descriptive name (for example, "Production Server")
  5. Choose when it expires and what it may do (see Key permissions)
  6. Copy and securely store your key

Using Your API Key

HTTP Requests

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

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

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

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

JavaScript
// 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
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"])

Environment Variables

For security, we recommend using environment variables instead of hardcoding API keys:

Bash
# .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:

  1. Create a new key and update your applications
  2. 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:

SettingWhat the key can do
AllEverything, including resources added in the future. Keys created before permissions existed have this setting.
Read onlyList and read voices and dictionaries. It cannot generate audio and cannot change anything.
RestrictedExactly the resources you allow, each set to None, Read or Write (or Allowed for resources that have no read access).
ResourceLevelsCovers
Text to speechNone, AllowedSpeech generation over HTTP and WebSocket, including the ElevenLabs, Vapi, Cognigy and Azure compatible endpoints
Realtime sessionsNone, AllowedRealtime voice sessions. Not yet available on the public API
Speech enhancementNone, AllowedSpeech enhancement
VoicesNone, Read, WriteRead lists and inspects voices. Write also clones, edits, publishes and deletes them
DictionariesNone, Read, WriteRead lists dictionaries and their entries. Write also creates, edits and deletes them
Organization projectsNone, Read, WriteRead 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

JSON
{
  "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

JSON
{
  "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:

JSON
{
  "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:

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

Next steps