Authentification de l’agent

Vue d’ensemble

Lors de la création d’agents conversationnels, vous devrez peut-être restreindre l’accès à certains agents ou conversations. ElevenLabs propose plusieurs mécanismes d’authentification pour garantir que seuls les utilisateurs autorisés puissent interagir avec vos agents.

Méthodes d’authentification

ElevenLabs propose deux méthodes principales pour sécuriser vos agents conversationnels :

Utiliser des URL signées

Les URL signées constituent l’approche recommandée pour les applications côté client. Cette méthode vous permet d’authentifier les utilisateurs sans exposer votre clé API.

Fonctionnement des URL signées

1. Votre serveur demande une URL signée à ElevenLabs à l’aide de votre clé API.
2. ElevenLabs génère un jeton temporaire et renvoie une URL WebSocket signée.
3. Votre application cliente utilise cette URL signée pour établir une connexion WebSocket.
4. L’URL signée expire après 15 minutes.

Générer une URL signée via l’API

Pour obtenir une URL signée, envoyez une requête au point de terminaison get_signed_url avec l’ID de votre agent :

# 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

La réponse curl se présente sous le format suivant :

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

Se connecter à votre agent avec une URL signée

Récupérez depuis le client l’URL signée générée par le serveur et utilisez-la pour vous connecter au 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}")

Expiration des URL signées

Les URL signées sont valides pendant 15 minutes. La session de conversation peut durer plus longtemps, mais la conversation doit être initiée dans ce délai de 15 minutes.

Utiliser des listes d’autorisation

Les listes d’autorisation permettent de restreindre l’accès à vos agents conversationnels selon le domaine d’origine. Ainsi, seules les requêtes provenant de domaines approuvés peuvent se connecter à votre agent.

Fonctionnement des listes d’autorisation

1. Vous configurez une liste de noms d’hôte approuvés pour votre agent.
2. Lorsqu’un client tente de se connecter, ElevenLabs vérifie si l’origine de la requête correspond à un nom d’hôte autorisé.
3. Si l’origine figure dans la liste d’autorisation, la connexion est permise, sinon elle est rejetée.

Configurer des listes d’autorisation

Les listes d’autorisation se configurent dans les paramètres d’authentification de votre agent. Vous pouvez indiquer jusqu’à 10 noms d’hôte uniques autorisés à se connecter à votre agent.

Exemple : configurer une liste d’autorisation

Choisir une méthode d’authentification

Configurez une méthode d’authentification par agent :

1. Utilisez les URL signées (enable_auth) pour les sessions client authentifiées.
2. Utilisez les listes d’autorisation (allowlist) pour le contrôle d’accès basé sur les noms d’hôte.

Ne configurez pas simultanément des URL signées et des listes d’autorisation sur le même agent. Choisissez la méthode correspondant à votre modèle de déploiement.

Exemple : URL signées uniquement

Utilisez enable_auth sans 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
    )
  )
)

Exemple : liste d’autorisation uniquement

Utilisez allowlist sans activer les URL signées :

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

FAQ