Authentication — ElevenLabs Documentation

Overview

When building conversational AI 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 AI agents:

Signed URLs

Generate temporary authenticated URLs for secure client-side connections without exposing API keys.

Allowlists

Restrict access to specific domains or hostnames that can connect to your agent.

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.

The guides below uses the JS client and Python SDK.

How signed URLs work

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

Never expose your ElevenLabs API key client-side.

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         client = ElevenLabs(api_key="your-api-key")
6         response = await client.conversational_ai.get_signed_url(agent_id="your-agent-id")
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=your-agent-id&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 client = ElevenLabs(api_key=api_key)
13 
14 conversation = Conversation(
15   client=client,
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=client,
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 AI agents based on the origin domain. This ensures that only requests from approved domains can connect to your agent.

How allowlists work

You configure a list of approved hostnames for your agent.
When a client attempts to connect, ElevenLabs checks if the request’s origin matches an allowed hostname.
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

1 from elevenlabs.client import ElevenLabs
2 import os
3 from elevenlabs.types import *
4 
5 api_key = os.getenv("ELEVENLABS_API_KEY")
6 client = ElevenLabs(api_key=api_key)
7 
8 agent = client.conversational_ai.create_agent(
9   conversation_config=ConversationalConfig(
10     agent=AgentConfig(
11       first_message="Hi. I'm an authenticated agent.",
12     )
13   ),
14   platform_settings=AgentPlatformSettingsRequestModel(
15   auth=AuthSettings(
16     enable_auth=False,
17     allowlist=[
18       AllowlistItem(hostname="example.com"),
19       AllowlistItem(hostname="app.example.com"),
20       AllowlistItem(hostname="localhost:3000")
21       ]
22     )
23   )
24 )

Combining authentication methods

For maximum security, you can combine both authentication methods:

Use enable_auth to require signed URLs.
Configure an allowlist to restrict which domains can request those signed URLs.

This creates a two-layer authentication system where clients must:

Connect from an approved domain
Possess a valid signed URL

1 from elevenlabs.client import ElevenLabs
2 import os
3 from elevenlabs.types import *
4 api_key = os.getenv("ELEVENLABS_API_KEY")
5 client = ElevenLabs(api_key=api_key)
6 agent = client.conversational_ai.create_agent(
7   conversation_config=ConversationalConfig(
8     agent=AgentConfig(
9       first_message="Hi. I'm an authenticated agent that can only be called from certain domains.",
10     )
11   ),
12   platform_settings=AgentPlatformSettingsRequestModel(
13   auth=AuthSettings(
14     enable_auth=True,
15     allowlist=[
16       AllowlistItem(hostname="example.com"),
17       AllowlistItem(hostname="app.example.com"),
18       AllowlistItem(hostname="localhost:3000")
19       ]
20     )
21   )
22 )

FAQ

Can I use the same signed URL for multiple users?

This is possible but we recommend generating a new signed URL for each user session.

What happens if the signed URL expires during a conversation?

If the signed URL expires (after 15 minutes), any WebSocket connection created with that signed url will not be closed, but trying to create a new connection with that signed URL will fail.

Can I restrict access to specific users?

The signed URL mechanism only verifies that the request came from an authorized source. To restrict access to specific users, implement user authentication in your application before requesting the signed URL.

Is there a limit to how many signed URLs I can generate?

There is no specific limit on the number of signed URLs you can generate.

How do allowlists handle subdomains?

Allowlists perform exact matching on hostnames. If you want to allow both a domain and its subdomains, you need to add each one separately (e.g., “example.com” and “app.example.com”).

Do I need to use both authentication methods?

No, you can use either signed URLs or allowlists independently based on your security requirements. For highest security, we recommend using both.

What other security measures should I implement?

Beyond signed URLs and allowlists, consider implementing:

User authentication before requesting signed URLs
Rate limiting on API requests
Usage monitoring for suspicious patterns
Proper error handling for auth failures

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

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

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	client = ElevenLabs(api_key=api_key)
13
14	conversation = Conversation(
15	client=client,
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=client,
27	url=signed_url,
28	)
29
30	conversation.start_session()
31	except Exception as error:
32	print(f"Failed to start conversation: {error}")

1	from elevenlabs.client import ElevenLabs
2	import os
3	from elevenlabs.types import *
4
5	api_key = os.getenv("ELEVENLABS_API_KEY")
6	client = ElevenLabs(api_key=api_key)
7
8	agent = client.conversational_ai.create_agent(
9	conversation_config=ConversationalConfig(
10	agent=AgentConfig(
11	first_message="Hi. I'm an authenticated agent.",
12	)
13	),
14	platform_settings=AgentPlatformSettingsRequestModel(
15	auth=AuthSettings(
16	enable_auth=False,
17	allowlist=[
18	AllowlistItem(hostname="example.com"),
19	AllowlistItem(hostname="app.example.com"),
20	AllowlistItem(hostname="localhost:3000")
21	]
22	)
23	)
24	)