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

# Autenticazione dell'agente

## Panoramica

Quando crei agenti conversazionali, potresti dover limitare l'accesso a determinati agenti o conversazioni. ElevenLabs offre diversi meccanismi di autenticazione per garantire che solo gli utenti autorizzati possano interagire con i tuoi agenti.

## Metodi di autenticazione

ElevenLabs offre due metodi principali per proteggere i tuoi agenti conversazionali:

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

Genera URL autenticati temporanei per connessioni client sicure senza esporre le chiavi API.

#### [Liste di autorizzazione](#using-allowlists)

Limita l'accesso a domini o hostname specifici che possono connettersi al tuo agente.

## Utilizzare gli URL firmati

Gli URL firmati sono l'approccio consigliato per le applicazioni client. Questo metodo ti permette di autenticare gli utenti senza esporre la tua chiave API.

> **Note**
>
> Le guide seguenti usano il [client JS](https://www.npmjs.com/package/@elevenlabs/client) e l'
> [SDK Python](https://github.com/elevenlabs/elevenlabs-python/).

### Come funzionano gli URL firmati

1. Il tuo server richiede un URL firmato a ElevenLabs usando la tua chiave API.
2. ElevenLabs genera un token temporaneo e restituisce un URL WebSocket firmato.
3. La tua applicazione client usa questo URL firmato per stabilire una connessione WebSocket.
4. L'URL firmato scade dopo 15 minuti.

> **Warning**
>
> Non esporre mai la tua chiave API di ElevenLabs lato client.

### Generare un URL firmato tramite l'API

Per ottenere un URL firmato, invia una richiesta all'[endpoint](/docs/it/eleven-agents/api-reference/conversations/get-signed-url) `get_signed_url` con l'ID del tuo 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 risposta curl ha il seguente formato:

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

### Connessione al tuo agente tramite un URL firmato

Recupera dal server l'URL firmato generato e usalo nel client per connetterti 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;
  }
}
```

### Scadenza dell'URL firmato

Gli URL firmati sono validi per 15 minuti. La sessione di conversazione può durare più a lungo, ma la conversazione deve essere avviata entro 15 minuti.

## Utilizzare le liste di autorizzazione

Le liste di autorizzazione ti consentono di limitare l'accesso ai tuoi agenti conversazionali in base al dominio di origine. In questo modo, solo le richieste provenienti da domini approvati possono connettersi al tuo agente.

### Come funzionano le liste di autorizzazione

1. Configuri un elenco di hostname approvati per il tuo agente.
2. Quando un client tenta di connettersi, ElevenLabs verifica se l'origine della richiesta corrisponde a un hostname consentito.
3. Se l'origine è nella lista di autorizzazione, la connessione è consentita; altrimenti, viene rifiutata.

### Configurare le liste di autorizzazione

Le liste di autorizzazione vengono configurate nelle impostazioni di autenticazione del tuo agente. Puoi specificare fino a 10 hostname univoci autorizzati a connettersi al tuo agente.

### Esempio: configurare una lista di autorizzazione

#### Configura dal dashboard

Apri il tuo agente nel dashboard e vai alla scheda **Sicurezza**. Aggiungi ogni hostname approvato (ad esempio, `example.com`, `app.example.com`, `localhost:3000`) alla lista di autorizzazione.

#### Configura tramite CLI

#### Scarica il tuo agente

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

#### Modifica la configurazione dell'agente

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

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

#### Invia le modifiche

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

#### Configura tramite 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;
  }
}
```

## Scegliere un metodo di autenticazione

Configura un metodo di autenticazione per agente:

1. Usa gli URL firmati (`enable_auth`) per le sessioni client autenticate.
2. Usa le liste di autorizzazione (`allowlist`) per il controllo degli accessi basato sugli hostname.

Non configurare URL firmati e liste di autorizzazione insieme sullo stesso agente. Scegli il metodo
più adatto al tuo modello di deployment.

### Esempio: solo URL firmati

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

### Esempio: solo lista di autorizzazione

Usa `allowlist` senza abilitare gli URL firmati:

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

## Domande frequenti

#### Posso usare lo stesso URL firmato per più utenti?

È possibile, ma ti consigliamo di generare un nuovo URL firmato per ogni sessione utente.

#### Cosa succede se l'URL firmato scade durante una conversazione?

Se l'URL firmato scade (dopo 15 minuti), le connessioni WebSocket create con quell'URL firmato
**non** verranno chiuse, ma la creazione di una nuova connessione con tale URL firmato
non riuscirà.

#### Posso limitare l'accesso a utenti specifici?

Il meccanismo degli URL firmati verifica soltanto che la richiesta provenga da una fonte autorizzata. Per
limitare l'accesso a utenti specifici, implementa l'autenticazione utente nella tua applicazione prima di
richiedere l'URL firmato.

#### Esiste un limite al numero di URL firmati che posso generare?

Non esiste un limite specifico al numero di URL firmati che puoi generare.

#### Come gestiscono le liste di autorizzazione i sottodomini?

Le liste di autorizzazione eseguono una corrispondenza esatta degli hostname. Se vuoi consentire sia un dominio sia i suoi
sottodomini, devi aggiungerli separatamente (ad esempio, "example.com" e "app.example.com").

#### Devo usare entrambi i metodi di autenticazione?

No. Configura URL firmati o una lista di autorizzazione per ciascun agente. Per le applicazioni
client, gli URL firmati sono l'impostazione predefinita consigliata.

#### Quali altre misure di sicurezza dovrei implementare?

Oltre agli URL firmati e alle liste di autorizzazione, valuta di implementare:

* Autenticazione utente prima di richiedere URL firmati
* Rate limiting sulle richieste API
* Monitoraggio dell'utilizzo per rilevare schemi sospetti
* Gestione corretta degli errori di autenticazione