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

# Autenticação de agente

## Visão geral

Ao criar agentes conversacionais, talvez você precise restringir o acesso a determinados agentes ou conversas. A ElevenLabs oferece vários mecanismos de autenticação para garantir que apenas usuários autorizados possam interagir com seus agentes.

## Métodos de autenticação

A ElevenLabs oferece dois métodos principais para proteger seus agentes conversacionais:

#### [URLs assinadas](#using-signed-urls)

Gere URLs temporárias autenticadas para conexões seguras no lado do cliente sem expor chaves de
API.

#### [Listas de permissão](#using-allowlists)

Restrinja o acesso a domínios ou nomes de host específicos que podem se conectar ao seu agente.

## Como usar URLs assinadas

URLs assinadas são a abordagem recomendada para aplicações do lado do cliente. Esse método permite autenticar usuários sem expor sua chave de API.

> **Note**
>
> Os guias abaixo usam o [cliente JS](https://www.npmjs.com/package/@elevenlabs/client) e o
> [SDK Python](https://github.com/elevenlabs/elevenlabs-python/).

### Como as URLs assinadas funcionam

1. Seu servidor solicita uma URL assinada à ElevenLabs usando sua chave de API.
2. A ElevenLabs gera um token temporário e retorna uma URL WebSocket assinada.
3. Sua aplicação cliente usa essa URL assinada para estabelecer uma conexão WebSocket.
4. A URL assinada expira após 15 minutos.

> **Warning**
>
> Nunca exponha sua chave de API da ElevenLabs no lado do cliente.

### Gerar uma URL assinada pela API

Para obter uma URL assinada, faça uma solicitação ao [endpoint](/docs/pt/eleven-agents/api-reference/conversations/get-signed-url) `get_signed_url` com o ID do seu 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"
```

A resposta do curl tem o seguinte formato:

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

### Como se conectar ao seu agente usando uma URL assinada

Recupere do cliente a URL assinada gerada pelo servidor e use-a para se conectar ao 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;
  }
}
```

### Expiração da URL assinada

As URLs assinadas são válidas por 15 minutos. A sessão de conversa pode durar mais, mas a conversa precisa ser iniciada dentro desse período de 15 minutos.

## Como usar listas de permissão

As listas de permissão permitem restringir o acesso aos seus agentes conversacionais com base no domínio de origem. Isso garante que apenas solicitações de domínios aprovados possam se conectar ao seu agente.

### Como as listas de permissão funcionam

1. Você configura uma lista de nomes de host aprovados para seu agente.
2. Quando um cliente tenta se conectar, a ElevenLabs verifica se a origem da solicitação corresponde a um nome de host permitido.
3. Se a origem estiver na lista de permissão, a conexão será permitida; caso contrário, será recusada.

### Como configurar listas de permissão

As listas de permissão são configuradas como parte das configurações de autenticação do seu agente. Você pode especificar até 10 nomes de host únicos autorizados a se conectar ao seu agente.

### Exemplo: configurar uma lista de permissão

#### Configurar pelo dashboard

Abra seu agente no dashboard e vá até a aba **Segurança**. Adicione cada nome de host aprovado (por exemplo, `example.com`, `app.example.com`, `localhost:3000`) à lista de permissão.

#### Configurar pela CLI

#### Baixar seu agente

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

#### Editar a configuração do agente

Em `agent_configs/<agent-name>.json`, defina `platform_settings.auth`:

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

#### Enviar as alterações

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

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

## Como escolher um método de autenticação

Configure um método de autenticação por agente:

1. Use URLs assinadas (`enable_auth`) para sessões autenticadas do cliente.
2. Use listas de permissão (`allowlist`) para controle de acesso baseado em nome de host.

Não configure URLs assinadas e listas de permissão juntas no mesmo agente. Escolha o método que corresponde ao seu modelo de implantação.

### Exemplo: somente URLs assinadas

Use `enable_auth` sem uma `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;
  }
}
```

### Exemplo: somente lista de permissão

Use `allowlist` sem habilitar URLs assinadas:

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

## Perguntas frequentes

#### Posso usar a mesma URL assinada para vários usuários?

Isso é possível, mas recomendamos gerar uma nova URL assinada para cada sessão de usuário.

#### O que acontece se a URL assinada expirar durante uma conversa?

Se a URL assinada expirar (após 15 minutos), qualquer conexão WebSocket criada com essa URL
não será fechada, mas tentar criar uma nova conexão com essa URL assinada falhará.

#### Posso restringir o acesso a usuários específicos?

O mecanismo de URL assinada verifica apenas se a solicitação veio de uma fonte autorizada. Para
restringir o acesso a usuários específicos, implemente a autenticação de usuários na sua aplicação antes
de solicitar a URL assinada.

#### Há um limite de URLs assinadas que posso gerar?

Não há um limite específico para o número de URLs assinadas que você pode gerar.

#### Como as listas de permissão lidam com subdomínios?

As listas de permissão fazem correspondência exata dos nomes de host. Se você quiser permitir um domínio e seus
subdomínios, precisará adicionar cada um separadamente (por exemplo, "example.com" e "app.example.com").

#### Preciso usar os dois métodos de autenticação?

Não. Configure URLs assinadas ou uma lista de permissão para cada agente. Para aplicações do lado do cliente,
URLs assinadas são a opção padrão recomendada.

#### Que outras medidas de segurança devo implementar?

Além de URLs assinadas e listas de permissão, considere implementar:

* Autenticação de usuários antes de solicitar URLs assinadas
* Limitação de taxa em solicitações de API
* Monitoramento de uso para identificar padrões suspeitos
* Tratamento adequado de erros de autenticação