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:

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.

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.

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:

Python

# 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

JavaScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

// Server-side code using the JavaScript SDK
const elevenlabs = new ElevenLabsClient({ apiKey: "your-api-key" });
async function getSignedUrl() {
  try {
    const response = await elevenlabs.conversationalAi.conversations.getSignedUrl({
      agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
    });

    return response.signed_url;
  } catch (error) {
    console.error("Error getting signed URL:", error);
    throw error;
  }
}

Bash

curl -X GET "https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6" \
-H "xi-api-key: your-api-key"

The curl response has the following format:

JSON

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

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.

Python

# 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}")

JavaScript

// Client-side code using the JavaScript SDK
import { Conversation } from "@elevenlabs/client";

async function startConversation() {
  try {
    const signedUrl = await getSignedUrl();
    const conversation = await Conversation.startSession({
      signedUrl,
    });

    return conversation;
  } catch (error) {
    console.error("Failed to start conversation:", error);
    throw 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

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

Configure via the dashboard

Open your agent in the dashboard and navigate to the Security tab. Add each approved hostname (e.g., example.com, app.example.com, localhost:3000) to the allowlist.

Configure via the CLI

Pull your agent

Bash

elevenlabs agents pull --agent "<agent-name>"

Edit the agent config

In agent_configs/<agent-name>.json, set platform_settings.auth:

JSON

{
  "platform_settings": {
    "auth": {
      "enable_auth": false,
      "allowlist": [
        { "hostname": "example.com" },
        { "hostname": "app.example.com" },
        { "hostname": "localhost:3000" }
      ]
    }
  }
}

Push the changes

Bash

elevenlabs agents push --agent "<agent-name>"

Configure via the API

Python

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'm an authenticated agent.",
    )
  ),
  platform_settings=AgentPlatformSettingsRequestModel(
  auth=AuthSettings(
    enable_auth=False,
    allowlist=[
      AllowlistItem(hostname="example.com"),
      AllowlistItem(hostname="app.example.com"),
      AllowlistItem(hostname="localhost:3000")
      ]
    )
  )
)

JavaScript

async function createAuthenticatedAgent(client) {
  try {
    const agent = await elevenlabs.conversationalAi.agents.create({
      conversationConfig: {
        agent: {
          firstMessage: "Hi. I'm an authenticated agent.",
        },
      },
      platformSettings: {
        auth: {
          enableAuth: false,
          allowlist: [
            { hostname: 'example.com' },
            { hostname: 'app.example.com' },
            { hostname: 'localhost:3000' },
          ],
        },
      },
    });

    return agent;
  } catch (error) {
    console.error('Error creating agent:', error);
    throw error;
  }
}

Choosing an authentication method

Configure one authentication method per agent:

Use signed URLs (enable_auth) for authenticated client sessions.
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:

Python

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

JavaScript

async function createSignedUrlAgent(client) {
  try {
    const agent = await client.conversationalAi.agents.create({
      conversationConfig: {
        agent: {
          firstMessage: "Hi. I require a signed URL.",
        },
      },
      platformSettings: {
        auth: {
          enableAuth: true,
        },
      },
    });

    return agent;
  } catch (error) {
    console.error("Error creating agent:", error);
    throw error;
  }
}

Example: allowlist only

Use allowlist without enabling signed URLs:

Python

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

JavaScript

async function createAllowlistAgent(client) {
  try {
    const agent = await client.conversationalAi.agents.create({
      conversationConfig: {
        agent: {
          firstMessage: "Hi. I only accept approved hostnames.",
        },
      },
      platformSettings: {
        auth: {
          allowlist: [{ hostname: "example.com" }, { hostname: "app.example.com" }],
        },
      },
    });

    return agent;
  } catch (error) {
    console.error("Error creating agent:", error);
    throw error;
  }
}

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. Configure either signed URLs or an allowlist for each agent. For client-side applications, signed URLs are the recommended default.

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

Search documentation

Help Center

Agent authentication

Overview

Authentication methods

Signed URLs

Allowlists

Using signed URLs

How signed URLs work

Generate a signed URL via the API

Connecting to your agent using a signed URL

Signed URL expiration

Using allowlists

How allowlists work

Configuring allowlists

Example: setting up an allowlist

Configure via the dashboard

Configure via the CLI

Pull your agent

Edit the agent config

Push the changes

Configure via the API

Choosing an authentication method

Example: signed URLs only

Example: allowlist only

FAQ

Can I use the same signed URL for multiple users?

What happens if the signed URL expires during a conversation?

Can I restrict access to specific users?

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

How do allowlists handle subdomains?

Do I need to use both authentication methods?

What other security measures should I implement?

Help Center