配置

智能体身份验证

了解如何保护对话式智能体的访问安全

概述

构建对话式智能体时，可能需要限制特定智能体或对话的访问权限。ElevenLabs 提供多种身份验证机制，确保只有获得授权的用户才能与智能体互动。

身份验证方法

ElevenLabs 提供两种主要方法来保护对话式智能体：

签名 URL

生成临时认证 URL，安全建立客户端连接，无需暴露 API 密钥。

允许列表

限制可连接到智能体的特定域名或主机名。

使用签名 URL

对于客户端应用，建议使用签名 URL。该方法可在不暴露 API 密钥的情况下验证用户身份。

以下指南使用 JS 客户端 和 Python SDK。

签名 URL 的工作原理

  1. 服务器使用 API 密钥向 ElevenLabs 请求签名 URL。
  2. ElevenLabs 生成临时令牌并返回签名 WebSocket URL。
  3. 客户端应用使用该签名 URL 建立 WebSocket 连接。
  4. 签名 URL 会在 15 分钟后过期。
切勿在客户端暴露 ElevenLabs API 密钥。

通过 API 生成签名 URL

要获取签名 URL，请使用智能体 ID 向 get_signed_url 端点发起请求：

# 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

curl 响应格式如下：

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

使用签名 URL 连接智能体

从客户端获取服务器生成的签名 URL，并使用该 URL 连接到 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}")

签名 URL 过期

签名 URL 的有效期为 15 分钟。对话会话可以持续更久，但必须在 15 分钟内发起对话。

使用允许列表

允许列表可根据来源域名限制对话式智能体的访问权限，确保只有来自已批准域名的请求才能连接到智能体。

允许列表的工作原理

  1. 为智能体配置已批准主机名列表。
  2. 客户端尝试连接时，ElevenLabs 会检查请求来源是否与允许的主机名匹配。
  3. 如果来源位于允许列表中，则允许连接；否则将被拒绝。

配置允许列表

允许列表是智能体身份验证设置的一部分。最多可指定 10 个唯一主机名连接到智能体。

示例：设置允许列表

在控制台中打开智能体，进入 安全 选项卡。将每个已批准的主机名（例如 example.com、app.example.com、localhost:3000）添加到允许列表。

选择身份验证方法

每个智能体配置一种身份验证方法：

  1. 对经过身份验证的客户端会话使用签名 URL（enable_auth）。
  2. 对基于主机名的访问控制使用允许列表（allowlist）。

不要在同一智能体上同时配置签名 URL 和允许列表。请选择与部署模式相符的方法。

示例：仅使用签名 URL

使用不含 allowlist 的 enable_auth：

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

示例：仅使用允许列表

使用 allowlist，不启用签名 URL：

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

常见问题

可以，但建议为每个用户会话生成新的签名 URL。

如果签名 URL 过期（15 分钟后），使用该签名 URL 创建的任何 WebSocket 连接都不会关闭，但尝试使用该签名 URL 创建新连接会失败。

签名 URL 机制仅验证请求是否来自授权来源。要限制特定用户访问，请在请求签名 URL 前，在应用中实现用户身份验证。

可生成的签名 URL 数量没有具体限制。

允许列表会精确匹配主机名。如果希望同时允许某个域名及其子域名，需要分别添加每一个（例如 “example.com” 和 “app.example.com”）。

不需要。为每个智能体配置签名 URL 或允许列表之一即可。对于客户端应用，建议默认使用签名 URL。

除签名 URL 和允许列表外，还可以考虑实施：

  • 请求签名 URL 前进行用户身份验证
  • 对 API 请求实施速率限制
  • 监控是否存在可疑的使用模式
  • 妥善处理身份验证失败的错误