> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Agenten-Authentifizierung

## Übersicht

Beim Erstellen von Conversational Agents müssen Sie möglicherweise den Zugriff auf bestimmte Agents oder Unterhaltungen beschränken. ElevenLabs bietet mehrere Authentifizierungsmechanismen, damit nur autorisierte Nutzer mit Ihren Agents interagieren können.

## Authentifizierungsmethoden

ElevenLabs bietet zwei primäre Methoden zum Absichern Ihrer Conversational Agents:

#### [Signierte URLs](#using-signed-urls)

Generieren Sie temporäre authentifizierte URLs für sichere clientseitige Verbindungen, ohne API-
Schlüssel offenzulegen.

#### [Zulassungslisten](#using-allowlists)

Beschränken Sie den Zugriff auf bestimmte Domains oder Hostnamen, die sich mit Ihrem Agent
verbinden können.

## Signierte URLs verwenden

Signierte URLs sind der empfohlene Ansatz für clientseitige Anwendungen. Mit dieser Methode können Sie Nutzer authentifizieren, ohne Ihren API-Schlüssel offenzulegen.

> **Note**
>
> In den folgenden Anleitungen werden der [JS-Client](https://www.npmjs.com/package/@elevenlabs/client) und
> das [Python SDK](https://github.com/elevenlabs/elevenlabs-python/) verwendet.

### So funktionieren signierte URLs

1. Ihr Server fordert mit Ihrem API-Schlüssel eine signierte URL von ElevenLabs an.
2. ElevenLabs generiert ein temporäres Token und gibt eine signierte WebSocket-URL zurück.
3. Ihre Client-Anwendung verwendet diese signierte URL, um eine WebSocket-Verbindung herzustellen.
4. Die signierte URL läuft nach 15 Minuten ab.

> **Warning**
>
> Geben Sie Ihren ElevenLabs-API-Schlüssel niemals clientseitig preis.

### Eine signierte URL über die API generieren

Um eine signierte URL zu erhalten, senden Sie eine Anfrage an den `get_signed_url`-[Endpunkt](/docs/de/eleven-agents/api-reference/conversations/get-signed-url) mit Ihrer Agent-ID:

```python
# Server-side code using the Python SDK
from elevenlabs.client import ElevenLabs
async def get_signed_url():
    try:
        elevenlabs = ElevenLabs(api_key="your-api-key")
        response = await elevenlabs.conversational_ai.conversations.get_signed_url(agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6")
        return response.signed_url
    except Exception as error:
        print(f"Error getting signed URL: {error}")
        raise
```

```javascript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

// Server-side code using the JavaScript SDK
const elevenlabs = new ElevenLabsClient({ apiKey: "your-api-key" });
async function getSignedUrl() {
  try {
    const response = await elevenlabs.conversationalAi.conversations.getSignedUrl({
      agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
    });

    return response.signed_url;
  } catch (error) {
    console.error("Error getting signed URL:", error);
    throw error;
  }
}
```

```bash
curl -X GET "https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6" \
-H "xi-api-key: your-api-key"
```

Die curl-Antwort hat folgendes Format:

```json
{
  "signed_url": "wss://api.elevenlabs.io/v1/convai/conversation?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&conversation_signature=your-token"
}
```

### Mit einer signierten URL eine Verbindung zu Ihrem Agent herstellen

Rufen Sie die vom Server generierte signierte URL im Client ab und verwenden Sie sie, um eine Verbindung zum WebSocket herzustellen.

```python
# Client-side code using the Python SDK
from elevenlabs.conversational_ai.conversation import (
    Conversation,
    AudioInterface,
    ClientTools,
    ConversationInitiationData
)
import os
from elevenlabs.client import ElevenLabs
api_key = os.getenv("ELEVENLABS_API_KEY")

elevenlabs = ElevenLabs(api_key=api_key)

conversation = Conversation(
  client=elevenlabs,
  agent_id=os.getenv("AGENT_ID"),
  requires_auth=True,
  audio_interface=AudioInterface(),
  config=ConversationInitiationData()
)

async def start_conversation():
  try:
    signed_url = await get_signed_url()
    conversation = Conversation(
      client=elevenlabs,
      url=signed_url,
    )

    conversation.start_session()
  except Exception as error:
    print(f"Failed to start conversation: {error}")

```

```javascript
// Client-side code using the JavaScript SDK
import { Conversation } from "@elevenlabs/client";

async function startConversation() {
  try {
    const signedUrl = await getSignedUrl();
    const conversation = await Conversation.startSession({
      signedUrl,
    });

    return conversation;
  } catch (error) {
    console.error("Failed to start conversation:", error);
    throw error;
  }
}
```

### Ablauf signierter URLs

Signierte URLs sind 15 Minuten lang gültig. Die Unterhaltungssitzung kann länger dauern, aber die Unterhaltung muss innerhalb des 15-Minuten-Fensters gestartet werden.

## Zulassungslisten verwenden

Zulassungslisten ermöglichen es, den Zugriff auf Ihre Conversational Agents anhand der Ursprungsdomain zu beschränken. So können sich nur Anfragen von genehmigten Domains mit Ihrem Agent verbinden.

### So funktionieren Zulassungslisten

1. Sie konfigurieren eine Liste genehmigter Hostnamen für Ihren Agent.
2. Wenn ein Client versucht, eine Verbindung herzustellen, prüft ElevenLabs, ob der Ursprung der Anfrage mit einem zugelassenen Hostnamen übereinstimmt.
3. Wenn sich der Ursprung auf der Zulassungsliste befindet, wird die Verbindung erlaubt, andernfalls abgelehnt.

### Zulassungslisten konfigurieren

Zulassungslisten werden als Teil der Authentifizierungseinstellungen Ihres Agent konfiguriert. Sie können bis zu 10 eindeutige Hostnamen angeben, die sich mit Ihrem Agent verbinden dürfen.

### Beispiel: Eine Zulassungsliste einrichten

#### Über das Dashboard konfigurieren

Öffnen Sie Ihren Agent im Dashboard und wechseln Sie zum Tab **Sicherheit**. Fügen Sie jeden genehmigten Hostnamen (z. B. `example.com`, `app.example.com`, `localhost:3000`) zur Zulassungsliste hinzu.

#### Über die CLI konfigurieren

#### Ihren Agent abrufen

```bash
elevenlabs agents pull --agent "<agent-name>"
```

#### Die Agent-Konfiguration bearbeiten

Setzen Sie in `agent_configs/<agent-name>.json` `platform_settings.auth`:

```json
{
  "platform_settings": {
    "auth": {
      "enable_auth": false,
      "allowlist": [
        { "hostname": "example.com" },
        { "hostname": "app.example.com" },
        { "hostname": "localhost:3000" }
      ]
    }
  }
}
```

#### Die Änderungen übertragen

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### Über die API konfigurieren

```python
from elevenlabs.client import ElevenLabs
import os
from elevenlabs.types import *

api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)

agent = elevenlabs.conversational_ai.agents.create(
  conversation_config=ConversationalConfig(
    agent=AgentConfig(
      first_message="Hi. I'm an authenticated agent.",
    )
  ),
  platform_settings=AgentPlatformSettingsRequestModel(
  auth=AuthSettings(
    enable_auth=False,
    allowlist=[
      AllowlistItem(hostname="example.com"),
      AllowlistItem(hostname="app.example.com"),
      AllowlistItem(hostname="localhost:3000")
      ]
    )
  )
)
```

```javascript
async function createAuthenticatedAgent(client) {
  try {
    const agent = await elevenlabs.conversationalAi.agents.create({
      conversationConfig: {
        agent: {
          firstMessage: "Hi. I'm an authenticated agent.",
        },
      },
      platformSettings: {
        auth: {
          enableAuth: false,
          allowlist: [
            { hostname: 'example.com' },
            { hostname: 'app.example.com' },
            { hostname: 'localhost:3000' },
          ],
        },
      },
    });

    return agent;
  } catch (error) {
    console.error('Error creating agent:', error);
    throw error;
  }
}
```

## Eine Authentifizierungsmethode wählen

Konfigurieren Sie pro Agent eine Authentifizierungsmethode:

1. Verwenden Sie signierte URLs (`enable_auth`) für authentifizierte Client-Sitzungen.
2. Verwenden Sie Zulassungslisten (`allowlist`) für die zugriffssteuerung nach Hostnamen.

Konfigurieren Sie signierte URLs und Zulassungslisten nicht gemeinsam für denselben Agent. Wählen Sie die Methode, die zu Ihrem Bereitstellungsmodell passt.

### Beispiel: Nur signierte URLs

Verwenden Sie `enable_auth` ohne `allowlist`:

```python
from elevenlabs.client import ElevenLabs
import os
from elevenlabs.types import *

api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)

agent = elevenlabs.conversational_ai.agents.create(
  conversation_config=ConversationalConfig(
    agent=AgentConfig(
      first_message="Hi. I require a signed URL.",
    )
  ),
  platform_settings=AgentPlatformSettingsRequestModel(
    auth=AuthSettings(
      enable_auth=True
    )
  )
)
```

```javascript
async function createSignedUrlAgent(client) {
  try {
    const agent = await client.conversationalAi.agents.create({
      conversationConfig: {
        agent: {
          firstMessage: "Hi. I require a signed URL.",
        },
      },
      platformSettings: {
        auth: {
          enableAuth: true,
        },
      },
    });

    return agent;
  } catch (error) {
    console.error("Error creating agent:", error);
    throw error;
  }
}
```

### Beispiel: Nur Zulassungsliste

Verwenden Sie `allowlist`, ohne signierte URLs zu aktivieren:

```python
from elevenlabs.client import ElevenLabs
import os
from elevenlabs.types import *

api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)

agent = elevenlabs.conversational_ai.agents.create(
  conversation_config=ConversationalConfig(
    agent=AgentConfig(
      first_message="Hi. I only accept approved hostnames.",
    )
  ),
  platform_settings=AgentPlatformSettingsRequestModel(
    auth=AuthSettings(
      allowlist=[
        AllowlistItem(hostname="example.com"),
        AllowlistItem(hostname="app.example.com"),
      ]
    )
  )
)
```

```javascript
async function createAllowlistAgent(client) {
  try {
    const agent = await client.conversationalAi.agents.create({
      conversationConfig: {
        agent: {
          firstMessage: "Hi. I only accept approved hostnames.",
        },
      },
      platformSettings: {
        auth: {
          allowlist: [{ hostname: "example.com" }, { hostname: "app.example.com" }],
        },
      },
    });

    return agent;
  } catch (error) {
    console.error("Error creating agent:", error);
    throw error;
  }
}
```

## FAQ

#### Kann ich dieselbe signierte URL für mehrere Nutzer verwenden?

Das ist möglich, wir empfehlen jedoch, für jede Nutzersitzung eine neue signierte URL zu generieren.

#### Was passiert, wenn die signierte URL während einer Unterhaltung abläuft?

Wenn die signierte URL abläuft (nach 15 Minuten), wird eine mit dieser signierten URL erstellte WebSocket-Verbindung
**nicht** geschlossen. Der Versuch, mit dieser signierten URL eine neue Verbindung zu erstellen, schlägt jedoch
fehl.

#### Kann ich den Zugriff auf bestimmte Nutzer beschränken?

Der Mechanismus für signierte URLs prüft nur, ob die Anfrage aus einer autorisierten Quelle stammt. Um
den Zugriff auf bestimmte Nutzer zu beschränken, implementieren Sie die Nutzerauthentifizierung in Ihrer Anwendung, bevor Sie
die signierte URL anfordern.

#### Gibt es ein Limit für die Anzahl signierter URLs, die ich generieren kann?

Für die Anzahl signierter URLs, die Sie generieren können, gibt es kein spezifisches Limit.

#### Wie behandeln Zulassungslisten Subdomains?

Zulassungslisten führen einen exakten Abgleich von Hostnamen durch. Wenn Sie sowohl eine Domain als auch ihre
Subdomains zulassen möchten, müssen Sie jede einzeln hinzufügen (z. B. "example.com" und "app.example.com").

#### Muss ich beide Authentifizierungsmethoden verwenden?

Nein. Konfigurieren Sie für jeden Agent entweder signierte URLs oder eine Zulassungsliste. Für clientseitige
Anwendungen sind signierte URLs die empfohlene Standardeinstellung.

#### Welche weiteren Sicherheitsmaßnahmen sollte ich implementieren?

Erwägen Sie zusätzlich zu signierten URLs und Zulassungslisten folgende Maßnahmen:

* Nutzerauthentifizierung vor dem Anfordern signierter URLs
* Ratenbegrenzung für API-Anfragen
* Nutzungsüberwachung auf verdächtige Muster
* Korrekte Fehlerbehandlung bei Authentifizierungsfehlern