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

# Agentauthenticatie

## Overzicht

Bij het bouwen van conversationele agents wil je mogelijk de toegang tot bepaalde agents of gesprekken beperken. ElevenLabs biedt meerdere authenticatiemechanismen om ervoor te zorgen dat alleen geautoriseerde gebruikers met je agents kunnen communiceren.

## Authenticatiemethoden

ElevenLabs biedt twee primaire methoden om je conversationele agents te beveiligen:

#### [Ondertekende URL's](#using-signed-urls)

Genereer tijdelijke, geauthenticeerde URL's voor veilige client-sideverbindingen zonder API-
sleutels bloot te geven.

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

Beperk toegang tot specifieke domeinen of hostnames die verbinding kunnen maken met je agent.

## Ondertekende URL's gebruiken

Ondertekende URL's zijn de aanbevolen aanpak voor client-sideapplicaties. Met deze methode kun je gebruikers authenticeren zonder je API-sleutel bloot te geven.

> **Note**
>
> In de onderstaande handleidingen worden de [JS-client](https://www.npmjs.com/package/@elevenlabs/client) en
> [Python SDK](https://github.com/elevenlabs/elevenlabs-python/) gebruikt.

### Hoe ondertekende URL's werken

1. Je server vraagt met je API-sleutel een ondertekende URL aan bij ElevenLabs.
2. ElevenLabs genereert een tijdelijk token en retourneert een ondertekende WebSocket-URL.
3. Je clientapplicatie gebruikt deze ondertekende URL om een WebSocket-verbinding tot stand te brengen.
4. De ondertekende URL verloopt na 15 minuten.

> **Warning**
>
> Geef je ElevenLabs API-sleutel nooit client-side bloot.

### Een ondertekende URL genereren via de API

Vraag een ondertekende URL aan via het `get_signed_url`-[endpoint](/docs/nl/eleven-agents/api-reference/conversations/get-signed-url) met je 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"
```

De curl-response heeft de volgende indeling:

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

### Verbinding maken met je agent via een ondertekende URL

Haal de door de server gegenereerde ondertekende URL op in de client en gebruik die om verbinding te maken met de websocket.

```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;
  }
}
```

### Verloop van ondertekende URL's

Ondertekende URL's zijn 15 minuten geldig. De gesprekssessie kan langer duren, maar het gesprek moet binnen het venster van 15 minuten worden gestart.

## Allowlists gebruiken

Allowlists bieden een manier om de toegang tot je conversationele agents te beperken op basis van het brondomein. Zo kunnen alleen requests van goedgekeurde domeinen verbinding maken met je agent.

### Hoe allowlists werken

1. Je configureert een lijst met goedgekeurde hostnames voor je agent.
2. Wanneer een client verbinding probeert te maken, controleert ElevenLabs of de oorsprong van de request overeenkomt met een toegestane hostname.
3. Als de oorsprong in de allowlist staat, wordt de verbinding toegestaan; anders wordt deze geweigerd.

### Allowlists configureren

Allowlists worden geconfigureerd als onderdeel van de authenticatie-instellingen van je agent. Je kunt maximaal 10 unieke hostnames opgeven die verbinding mogen maken met je agent.

### Voorbeeld: een allowlist instellen

#### Configureren via het dashboard

Open je agent in het dashboard en ga naar het tabblad **Beveiliging**. Voeg elke goedgekeurde hostname (bijvoorbeeld `example.com`, `app.example.com`, `localhost:3000`) toe aan de allowlist.

#### Configureren via de CLI

#### Haal je agent op

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

#### Bewerk de agentconfiguratie

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

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

#### Push de wijzigingen

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

#### Configureren via de API

```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;
  }
}
```

## Een authenticatiemethode kiezen

Configureer één authenticatiemethode per agent:

1. Gebruik ondertekende URL's (`enable_auth`) voor geauthenticeerde clientsessies.
2. Gebruik allowlists (`allowlist`) voor toegangsbeheer op basis van hostnames.

Configureer niet zowel ondertekende URL's als allowlists voor dezelfde agent. Kies de methode die
bij je implementatiemodel past.

### Voorbeeld: alleen ondertekende URL's

Gebruik `enable_auth` zonder een `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;
  }
}
```

### Voorbeeld: alleen allowlist

Gebruik `allowlist` zonder ondertekende URL's in te schakelen:

```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;
  }
}
```

## Veelgestelde vragen

#### Kan ik dezelfde ondertekende URL voor meerdere gebruikers gebruiken?

Dit is mogelijk, maar we raden aan om voor elke gebruikerssessie een nieuwe ondertekende URL te genereren.

#### Wat gebeurt er als de ondertekende URL tijdens een gesprek verloopt?

Als de ondertekende URL verloopt (na 15 minuten), wordt een WebSocket-verbinding die met die ondertekende
URL is gemaakt **niet** gesloten, maar het maken van een nieuwe verbinding met die ondertekende URL
mislukt.

#### Kan ik toegang beperken tot specifieke gebruikers?

Het mechanisme voor ondertekende URL's controleert alleen of de request van een geautoriseerde bron afkomstig is. Om
toegang tot specifieke gebruikers te beperken, implementeer je gebruikersauthenticatie in je applicatie voordat je
de ondertekende URL aanvraagt.

#### Is er een limiet aan het aantal ondertekende URL's dat ik kan genereren?

Er is geen specifieke limiet voor het aantal ondertekende URL's dat je kunt genereren.

#### Hoe gaan allowlists om met subdomeinen?

Allowlists voeren exacte matching uit op hostnames. Als je zowel een domein als de bijbehorende
subdomeinen wilt toestaan, moet je elk domein afzonderlijk toevoegen (bijvoorbeeld "example.com" en "app.example.com").

#### Moet ik beide authenticatiemethoden gebruiken?

Nee. Configureer voor elke agent óf ondertekende URL's óf een allowlist. Voor client-side-
applicaties zijn ondertekende URL's de aanbevolen standaardoptie.

#### Welke andere beveiligingsmaatregelen moet ik implementeren?

Overweeg naast ondertekende URL's en allowlists ook het volgende te implementeren:

* Gebruikersauthenticatie voordat je ondertekende URL's aanvraagt
* Rate limiting voor API-requests
* Gebruiksmonitoring voor verdachte patronen
* Goede foutafhandeling voor authenticatiefouten