구성

에이전트 인증

대화형 에이전트에 대한 액세스를 보호하는 방법을 알아보세요.

개요

대화형 에이전트를 구축할 때 특정 에이전트나 대화에 대한 접근을 제한해야 할 수 있습니다. ElevenLabs는 승인된 사용자만 에이전트와 상호작용할 수 있도록 여러 인증 메커니즘을 제공합니다.

인증 방법

ElevenLabs는 대화형 에이전트를 보호하기 위한 두 가지 주요 방법을 제공합니다.

서명된 URL

API 키를 노출하지 않고도 안전한 클라이언트 측 연결을 위한 임시 인증 URL을 생성합니다.

허용 목록

에이전트에 연결할 수 있는 특정 도메인 또는 호스트 이름으로 접근을 제한합니다.

서명된 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
    )
  )
)

예시: 허용 목록만 사용

서명된 URL을 활성화하지 않고 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 only accept approved hostnames.",
    )
  ),
  platform_settings=AgentPlatformSettingsRequestModel(
    auth=AuthSettings(
      allowlist=[
        AllowlistItem(hostname="example.com"),
        AllowlistItem(hostname="app.example.com"),
      ]
    )
  )
)

FAQ

가능하지만, 각 사용자 세션마다 새 서명된 URL을 생성하는 것이 좋습니다.

서명된 URL이 만료되더라도(15분 후) 해당 URL로 생성된 WebSocket 연결은 닫히지 않습니다. 하지만 그 서명된 URL로 새 연결을 만들려고 하면 실패합니다.

서명된 URL 메커니즘은 요청이 승인된 소스에서 왔는지만 확인합니다. 특정 사용자로 접근을 제한하려면 서명된 URL을 요청하기 전에 애플리케이션에서 사용자 인증을 구현하세요.

생성할 수 있는 서명된 URL 수에는 별도의 제한이 없습니다.

허용 목록은 호스트 이름을 정확히 일치시켜 확인합니다. 도메인과 하위 도메인을 모두 허용하려면 각각 별도로 추가해야 합니다(예: “example.com” 및 “app.example.com”).

아니요. 에이전트마다 서명된 URL 또는 허용 목록 중 하나를 구성하세요. 클라이언트 측 애플리케이션에는 서명된 URL이 권장되는 기본 방식입니다.

서명된 URL과 허용 목록 외에도 다음 구현을 고려하세요.

  • 서명된 URL 요청 전 사용자 인증
  • API 요청에 대한 속도 제한
  • 의심스러운 패턴에 대한 사용량 모니터링
  • 인증 실패에 대한 적절한 오류 처리