Agent authentication

Overview

When building conversational agents, you may need to restrict access to certain agents or conversations. ElevenLabs provides multiple authentication mechanisms to ensure only authorized users can interact with your agents.

Authentication methods

ElevenLabs offers two primary methods to secure your conversational agents:

Using signed URLs

Signed URLs are the recommended approach for client-side applications. This method allows you to authenticate users without exposing your API key.

How signed URLs work

1. Your server requests a signed URL from ElevenLabs using your API key.
2. ElevenLabs generates a temporary token and returns a signed WebSocket URL.
3. Your client application uses this signed URL to establish a WebSocket connection.
4. The signed URL expires after 15 minutes.

Generate a signed URL via the API

To obtain a signed URL, make a request to the get_signed_url endpoint with your agent ID:

1
# Server-side code using the Python SDK
2
from elevenlabs.client import ElevenLabs
3
async def get_signed_url():
4
    try:
5
        elevenlabs = ElevenLabs(api_key="your-api-key")
6
        response = await elevenlabs.conversational_ai.conversations.get_signed_url(agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6")
7
        return response.signed_url
8
    except Exception as error:
9
        print(f"Error getting signed URL: {error}")
10
        raise

The curl response has the following format:

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

Connecting to your agent using a signed URL

Retrieve the server generated signed URL from the client and use the signed URL to connect to the websocket.

1
# Client-side code using the Python SDK
2
from elevenlabs.conversational_ai.conversation import (
3
    Conversation,
4
    AudioInterface,
5
    ClientTools,
6
    ConversationInitiationData
7
)
8
import os
9
from elevenlabs.client import ElevenLabs
10
api_key = os.getenv("ELEVENLABS_API_KEY")
11
12
elevenlabs = ElevenLabs(api_key=api_key)
13
14
conversation = Conversation(
15
  client=elevenlabs,
16
  agent_id=os.getenv("AGENT_ID"),
17
  requires_auth=True,
18
  audio_interface=AudioInterface(),
19
  config=ConversationInitiationData()
20
)
21
22
async def start_conversation():
23
  try:
24
    signed_url = await get_signed_url()
25
    conversation = Conversation(
26
      client=elevenlabs,
27
      url=signed_url,
28
    )
29
30
    conversation.start_session()
31
  except Exception as error:
32
    print(f"Failed to start conversation: {error}")

Signed URL expiration

Signed URLs are valid for 15 minutes. The conversation session can last longer, but the conversation must be initiated within the 15 minute window.

Using allowlists

Allowlists provide a way to restrict access to your conversational agents based on the origin domain. This ensures that only requests from approved domains can connect to your agent.

How allowlists work

1. You configure a list of approved hostnames for your agent.
2. When a client attempts to connect, ElevenLabs checks if the request’s origin matches an allowed hostname.
3. If the origin is on the allowlist, the connection is permitted; otherwise, it’s rejected.

Configuring allowlists

Allowlists are configured as part of your agent’s authentication settings. You can specify up to 10 unique hostnames that are allowed to connect to your agent.

Example: setting up an allowlist

Choosing an authentication method

Configure one authentication method per agent:

1. Use signed URLs (enable_auth) for authenticated client sessions.
2. Use allowlists (allowlist) for hostname-based access control.

Do not configure signed URLs and allowlists together on the same agent. Choose the method that matches your deployment model.

Example: signed URLs only

Use enable_auth without an allowlist:

1
from elevenlabs.client import ElevenLabs
2
import os
3
from elevenlabs.types import *
4
5
api_key = os.getenv("ELEVENLABS_API_KEY")
6
elevenlabs = ElevenLabs(api_key=api_key)
7
8
agent = elevenlabs.conversational_ai.agents.create(
9
  conversation_config=ConversationalConfig(
10
    agent=AgentConfig(
11
      first_message="Hi. I require a signed URL.",
12
    )
13
  ),
14
  platform_settings=AgentPlatformSettingsRequestModel(
15
    auth=AuthSettings(
16
      enable_auth=True
17
    )
18
  )
19
)

Example: allowlist only

Use allowlist without enabling signed URLs:

1
from elevenlabs.client import ElevenLabs
2
import os
3
from elevenlabs.types import *
4
5
api_key = os.getenv("ELEVENLABS_API_KEY")
6
elevenlabs = ElevenLabs(api_key=api_key)
7
8
agent = elevenlabs.conversational_ai.agents.create(
9
  conversation_config=ConversationalConfig(
10
    agent=AgentConfig(
11
      first_message="Hi. I only accept approved hostnames.",
12
    )
13
  ),
14
  platform_settings=AgentPlatformSettingsRequestModel(
15
    auth=AuthSettings(
16
      allowlist=[
17
        AllowlistItem(hostname="example.com"),
18
        AllowlistItem(hostname="app.example.com"),
19
      ]
20
    )
21
  )
22
)

FAQ