Autenticação de agente

Visão geral

Ao criar agentes conversacionais, talvez você precise restringir o acesso a determinados agentes ou conversas. A ElevenLabs oferece vários mecanismos de autenticação para garantir que apenas usuários autorizados possam interagir com seus agentes.

Métodos de autenticação

A ElevenLabs oferece dois métodos principais para proteger seus agentes conversacionais:

Como usar URLs assinadas

URLs assinadas são a abordagem recomendada para aplicações do lado do cliente. Esse método permite autenticar usuários sem expor sua chave de API.

Como as URLs assinadas funcionam

1. Seu servidor solicita uma URL assinada à ElevenLabs usando sua chave de API.
2. A ElevenLabs gera um token temporário e retorna uma URL WebSocket assinada.
3. Sua aplicação cliente usa essa URL assinada para estabelecer uma conexão WebSocket.
4. A URL assinada expira após 15 minutos.

Gerar uma URL assinada pela API

Para obter uma URL assinada, faça uma solicitação ao endpoint get_signed_url com o ID do seu agente:

# 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

A resposta do curl tem o seguinte formato:

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

Como se conectar ao seu agente usando uma URL assinada

Recupere do cliente a URL assinada gerada pelo servidor e use-a para se conectar ao 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}")

Expiração da URL assinada

As URLs assinadas são válidas por 15 minutos. A sessão de conversa pode durar mais, mas a conversa precisa ser iniciada dentro desse período de 15 minutos.

Como usar listas de permissão

As listas de permissão permitem restringir o acesso aos seus agentes conversacionais com base no domínio de origem. Isso garante que apenas solicitações de domínios aprovados possam se conectar ao seu agente.

Como as listas de permissão funcionam

1. Você configura uma lista de nomes de host aprovados para seu agente.
2. Quando um cliente tenta se conectar, a ElevenLabs verifica se a origem da solicitação corresponde a um nome de host permitido.
3. Se a origem estiver na lista de permissão, a conexão será permitida; caso contrário, será recusada.

Como configurar listas de permissão

As listas de permissão são configuradas como parte das configurações de autenticação do seu agente. Você pode especificar até 10 nomes de host únicos autorizados a se conectar ao seu agente.

Exemplo: configurar uma lista de permissão

Como escolher um método de autenticação

Configure um método de autenticação por agente:

1. Use URLs assinadas (enable_auth) para sessões autenticadas do cliente.
2. Use listas de permissão (allowlist) para controle de acesso baseado em nome de host.

Não configure URLs assinadas e listas de permissão juntas no mesmo agente. Escolha o método que corresponde ao seu modelo de implantação.

Exemplo: somente URLs assinadas

Use enable_auth sem uma 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
    )
  )
)

Exemplo: somente lista de permissão

Use allowlist sem habilitar URLs assinadas:

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

Perguntas frequentes