> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Autenticación de agentes

## Descripción general

Al crear agentes conversacionales, puede que necesites restringir el acceso a determinados agentes o conversaciones. ElevenLabs ofrece varios mecanismos de autenticación para garantizar que solo usuarios autorizados puedan interactuar con tus agentes.

## Métodos de autenticación

ElevenLabs ofrece dos métodos principales para proteger tus agentes conversacionales:

#### [URL firmadas](#using-signed-urls)

Genera URL autenticadas temporales para conexiones seguras del lado del cliente sin exponer claves
de API.

#### [Listas de permitidos](#using-allowlists)

Restringe el acceso a dominios o nombres de host específicos que puedan conectarse a tu agente.

## Uso de URL firmadas

Las URL firmadas son el enfoque recomendado para aplicaciones del lado del cliente. Este método te permite autenticar usuarios sin exponer tu clave de API.

> **Note**
>
> Las siguientes guías usan el [cliente de JS](https://www.npmjs.com/package/@elevenlabs/client) y
> el [SDK de Python](https://github.com/elevenlabs/elevenlabs-python/).

### Cómo funcionan las URL firmadas

1. Tu servidor solicita una URL firmada a ElevenLabs mediante tu clave de API.
2. ElevenLabs genera un token temporal y devuelve una URL de WebSocket firmada.
3. Tu aplicación cliente usa esta URL firmada para establecer una conexión WebSocket.
4. La URL firmada caduca después de 15 minutos.

> **Warning**
>
> Nunca expongas tu clave de API de ElevenLabs del lado del cliente.

### Generar una URL firmada mediante la API

Para obtener una URL firmada, realiza una solicitud al [endpoint](/docs/es/eleven-agents/api-reference/conversations/get-signed-url) `get_signed_url` con el ID de tu agente:

```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"
```

La respuesta de curl tiene el siguiente formato:

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

### Conectarte a tu agente mediante una URL firmada

Recupera del cliente la URL firmada generada por el servidor y úsala para conectarte al 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;
  }
}
```

### Caducidad de las URL firmadas

Las URL firmadas son válidas durante 15 minutos. La sesión de conversación puede durar más, pero debes iniciar la conversación dentro de ese plazo de 15 minutos.

## Uso de listas de permitidos

Las listas de permitidos permiten restringir el acceso a tus agentes conversacionales según el dominio de origen. Esto garantiza que solo las solicitudes procedentes de dominios aprobados puedan conectarse a tu agente.

### Cómo funcionan las listas de permitidos

1. Configuras una lista de nombres de host aprobados para tu agente.
2. Cuando un cliente intenta conectarse, ElevenLabs comprueba si el origen de la solicitud coincide con un nombre de host permitido.
3. Si el origen está en la lista de permitidos, se permite la conexión; de lo contrario, se rechaza.

### Configurar listas de permitidos

Las listas de permitidos se configuran como parte de los ajustes de autenticación de tu agente. Puedes especificar hasta 10 nombres de host únicos autorizados para conectarse a tu agente.

### Ejemplo: configurar una lista de permitidos

#### Configurar desde el panel

Abre tu agente en el panel y ve a la pestaña **Seguridad**. Añade cada nombre de host aprobado (por ejemplo, `example.com`, `app.example.com`, `localhost:3000`) a la lista de permitidos.

#### Configurar mediante la CLI

#### Descarga tu agente

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

#### Edita la configuración del agente

En `agent_configs/<agent-name>.json`, establece `platform_settings.auth`:

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

#### Envía los cambios

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

#### Configurar mediante la 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;
  }
}
```

## Elegir un método de autenticación

Configura un método de autenticación por agente:

1. Usa URL firmadas (`enable_auth`) para sesiones autenticadas del cliente.
2. Usa listas de permitidos (`allowlist`) para controlar el acceso según el nombre de host.

No configures URL firmadas y listas de permitidos a la vez para el mismo agente. Elige el método que
se ajuste a tu modelo de implementación.

### Ejemplo: solo URL firmadas

Usa `enable_auth` sin una `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;
  }
}
```

### Ejemplo: solo lista de permitidos

Usa `allowlist` sin habilitar las URL firmadas:

```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;
  }
}
```

## Preguntas frecuentes

#### ¿Puedo usar la misma URL firmada para varios usuarios?

Es posible, pero recomendamos generar una nueva URL firmada para cada sesión de usuario.

#### ¿Qué ocurre si la URL firmada caduca durante una conversación?

Si la URL firmada caduca (después de 15 minutos), cualquier conexión WebSocket creada con esa URL
no se cerrará, pero no podrás crear una nueva conexión con esa URL firmada.

#### ¿Puedo restringir el acceso a usuarios específicos?

El mecanismo de URL firmadas solo verifica que la solicitud provenga de una fuente autorizada. Para
restringir el acceso a usuarios específicos, implementa autenticación de usuarios en tu aplicación antes de
solicitar la URL firmada.

#### ¿Hay un límite en el número de URL firmadas que puedo generar?

No hay un límite específico en el número de URL firmadas que puedes generar.

#### ¿Cómo gestionan las listas de permitidos los subdominios?

Las listas de permitidos realizan una coincidencia exacta de los nombres de host. Si quieres permitir tanto un dominio como sus
subdominios, debes añadir cada uno por separado (por ejemplo, "example.com" y "app.example.com").

#### ¿Tengo que usar ambos métodos de autenticación?

No. Configura URL firmadas o una lista de permitidos para cada agente. Para aplicaciones del lado del cliente,
las URL firmadas son la opción predeterminada recomendada.

#### ¿Qué otras medidas de seguridad debo implementar?

Además de las URL firmadas y las listas de permitidos, considera implementar:

* Autenticación de usuarios antes de solicitar URL firmadas
* Limitación de velocidad en las solicitudes a la API
* Monitorización del uso para detectar patrones sospechosos
* Gestión adecuada de errores de autenticación