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

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.

Een ondertekende URL genereren via de API

Vraag een ondertekende URL aan via het get_signed_url-endpoint met je agent-ID:

# 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

De curl-response heeft de volgende indeling:

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

# 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}")

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

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:

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

Voorbeeld: alleen allowlist

Gebruik allowlist zonder ondertekende URL’s in te schakelen:

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"),
      ]
    )
  )
)

Veelgestelde vragen