> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kugelaudio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the KugelAudio API

All API requests require authentication using an API key. This page explains how to obtain and use your API key.

## Getting Your API Key

1. Sign up at [kugelaudio.com](https://kugelaudio.com)
2. Go to your [Dashboard](https://kugelaudio.com/dashboard)
3. Navigate to **Settings** → **API Keys**
4. Click **Create API Key**
5. Copy and securely store your key

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

## Using Your API Key

### HTTP Requests

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

```bash theme={null}
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"}'
```

### WebSocket Connections

For WebSocket connections, pass the API key as a query parameter:

```javascript theme={null}
const ws = new WebSocket('wss://api.kugelaudio.com/ws/tts?api_key=YOUR_API_KEY');
```

Or in the headers (where supported):

```python theme={null}
import websockets

async with websockets.connect(
    "wss://api.kugelaudio.com/ws/tts",
    extra_headers={"Authorization": "Bearer YOUR_API_KEY"}
) as ws:
    # ...
```

### SDK Usage

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from kugelaudio import KugelAudio

    # Pass directly
    client = KugelAudio(api_key="YOUR_API_KEY")

    # Or use environment variable
    # export KUGELAUDIO_API_KEY=YOUR_API_KEY
    client = KugelAudio()  # Reads from env
    ```
  </Tab>

  <Tab title="JavaScript">
    ```typescript theme={null}
    import { KugelAudio } from 'kugelaudio';

    // Pass directly
    const client = new KugelAudio({ apiKey: 'YOUR_API_KEY' });

    // Or use environment variable
    // KUGELAUDIO_API_KEY=YOUR_API_KEY
    const client = new KugelAudio();  // Reads from env
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    # 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/models \
      -H "Authorization: Bearer $KUGELAUDIO_API_KEY"
    ```
  </Tab>
</Tabs>

## Environment Variables

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

```bash theme={null}
# .env file
KUGELAUDIO_API_KEY=your_api_key_here
```

The SDKs automatically read from `KUGELAUDIO_API_KEY` if no key is provided.
Traffic goes to the canonical geo-routed endpoint by default. Prefix your key
with `eu-` to use the direct EU endpoint. See [Regions](/guides/regions).

## API Key Security

<AccordionGroup>
  <Accordion title="Never expose keys in client-side code" icon="eye-slash">
    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
  </Accordion>

  <Accordion title="Use environment variables" icon="lock">
    Store API keys in environment variables, not in code:

    ```bash theme={null}
    export KUGELAUDIO_API_KEY=your_key_here
    ```
  </Accordion>

  <Accordion title="Rotate keys regularly" icon="rotate">
    Create new API keys periodically and delete old ones. This limits the impact of any potential key exposure.
  </Accordion>

  <Accordion title="Use separate keys for environments" icon="layer-group">
    Create separate API keys for development, staging, and production. This makes it easier to rotate keys and track usage.
  </Accordion>
</AccordionGroup>

## Managing API Keys

### Creating Keys

1. Go to **Dashboard** → **Settings** → **API Keys**
2. Click **Create API Key**
3. Give it a descriptive name (e.g., "Production Server")
4. Copy the key immediately (it won't be shown again)

### Revoking Keys

If a key is compromised:

1. Go to **Dashboard** → **Settings** → **API Keys**
2. Find the compromised key
3. Click **Revoke**
4. Create a new key
5. Update your applications

<Note>
  Revoked keys stop working immediately. Make sure to update all applications using the key before revoking.
</Note>

### Key Permissions

All API keys have full access to your account's resources. We're working on scoped permissions for future releases.

## Authentication Errors

### 401 Unauthorized

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}
```

**Causes:**

* Missing `Authorization` header
* Invalid API key
* Revoked API key
* Malformed header format

**Solutions:**

* Check that you're including the `Authorization` header
* Verify the API key is correct
* Check if the key has been revoked
* Ensure format is `Bearer YOUR_API_KEY`

### 403 Forbidden

```json theme={null}
{
  "error": {
    "code": "forbidden",
    "message": "API key does not have access to this resource"
  }
}
```

**Causes:**

* Trying to access resources from another account
* Feature not available on your plan

**Solutions:**

* Verify you're using the correct API key
* Check your plan includes the feature you're trying to use

## Testing Authentication

Verify your API key is working:

```bash theme={null}
curl -X GET "https://api.kugelaudio.com/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Expected response:

```json theme={null}
{
  "models": [
    {
      "id": "kugel-3",
      "model_id": "kugel-3",
      "name": "Kugel 3",
      "max_input_length": 10000,
      "sample_rate": 24000
    }
  ]
}
```

Legacy IDs such as `kugel-2.5` and `kugel-2-turbo` remain accepted for backwards compatibility. New integrations should use `kugel-3`.