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

# Authentification de l’agent

## Vue d’ensemble

Lors de la création d’agents conversationnels, vous devrez peut-être restreindre l’accès à certains agents ou conversations. ElevenLabs propose plusieurs mécanismes d’authentification pour garantir que seuls les utilisateurs autorisés puissent interagir avec vos agents.

## Méthodes d’authentification

ElevenLabs propose deux méthodes principales pour sécuriser vos agents conversationnels :

#### [URL signées](#using-signed-urls)

Générez des URL temporaires authentifiées pour des connexions côté client sécurisées, sans exposer vos clés API.

#### [Listes d’autorisation](#using-allowlists)

Restreignez l’accès à des domaines ou noms d’hôte spécifiques pouvant se connecter à votre agent.

## Utiliser des URL signées

Les URL signées constituent l’approche recommandée pour les applications côté client. Cette méthode vous permet d’authentifier les utilisateurs sans exposer votre clé API.

> **Note**
>
> Les guides ci-dessous utilisent le [client JS](https://www.npmjs.com/package/@elevenlabs/client) et le
> [SDK Python](https://github.com/elevenlabs/elevenlabs-python/).

### Fonctionnement des URL signées

1. Votre serveur demande une URL signée à ElevenLabs à l’aide de votre clé API.
2. ElevenLabs génère un jeton temporaire et renvoie une URL WebSocket signée.
3. Votre application cliente utilise cette URL signée pour établir une connexion WebSocket.
4. L’URL signée expire après 15 minutes.

> **Warning**
>
> N’exposez jamais votre clé API ElevenLabs côté client.

### Générer une URL signée via l’API

Pour obtenir une URL signée, envoyez une requête au [point de terminaison](/docs/fr/eleven-agents/api-reference/conversations/get-signed-url) `get_signed_url` avec l’ID de votre agent :

```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 réponse curl se présente sous le format suivant :

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

### Se connecter à votre agent avec une URL signée

Récupérez depuis le client l’URL signée générée par le serveur et utilisez-la pour vous connecter au 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;
  }
}
```

### Expiration des URL signées

Les URL signées sont valides pendant 15 minutes. La session de conversation peut durer plus longtemps, mais la conversation doit être initiée dans ce délai de 15 minutes.

## Utiliser des listes d’autorisation

Les listes d’autorisation permettent de restreindre l’accès à vos agents conversationnels selon le domaine d’origine. Ainsi, seules les requêtes provenant de domaines approuvés peuvent se connecter à votre agent.

### Fonctionnement des listes d’autorisation

1. Vous configurez une liste de noms d’hôte approuvés pour votre agent.
2. Lorsqu’un client tente de se connecter, ElevenLabs vérifie si l’origine de la requête correspond à un nom d’hôte autorisé.
3. Si l’origine figure dans la liste d’autorisation, la connexion est permise, sinon elle est rejetée.

### Configurer des listes d’autorisation

Les listes d’autorisation se configurent dans les paramètres d’authentification de votre agent. Vous pouvez indiquer jusqu’à 10 noms d’hôte uniques autorisés à se connecter à votre agent.

### Exemple : configurer une liste d’autorisation

#### Configurer via le Dashboard

Ouvrez votre agent dans le Dashboard et accédez à l’onglet **Sécurité**. Ajoutez chaque nom d’hôte approuvé (par exemple, `example.com`, `app.example.com`, `localhost:3000`) à la liste d’autorisation.

#### Configurer via la CLI

#### Récupérer votre agent

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

#### Modifier la configuration de l’agent

Dans `agent_configs/<agent-name>.json`, définissez `platform_settings.auth` :

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

#### Envoyer les modifications

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

#### Configurer via l’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;
  }
}
```

## Choisir une méthode d’authentification

Configurez une méthode d’authentification par agent :

1. Utilisez les URL signées (`enable_auth`) pour les sessions client authentifiées.
2. Utilisez les listes d’autorisation (`allowlist`) pour le contrôle d’accès basé sur les noms d’hôte.

Ne configurez pas simultanément des URL signées et des listes d’autorisation sur le même agent. Choisissez la méthode correspondant à votre modèle de déploiement.

### Exemple : URL signées uniquement

Utilisez `enable_auth` sans `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;
  }
}
```

### Exemple : liste d’autorisation uniquement

Utilisez `allowlist` sans activer les URL signées :

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

#### Puis-je utiliser la même URL signée pour plusieurs utilisateurs ?

C’est possible, mais nous vous recommandons de générer une nouvelle URL signée pour chaque session utilisateur.

#### Que se passe-t-il si l’URL signée expire au cours d’une conversation ?

Si l’URL signée expire, après 15 minutes, toute connexion WebSocket créée avec cette URL signée ne sera **pas** fermée, mais toute tentative de créer une nouvelle connexion avec cette URL signée échouera.

#### Puis-je restreindre l’accès à certains utilisateurs ?

Le mécanisme d’URL signée vérifie uniquement que la requête provient d’une source autorisée. Pour restreindre l’accès à certains utilisateurs, mettez en œuvre une authentification utilisateur dans votre application avant de demander l’URL signée.

#### Le nombre d’URL signées que je peux générer est-il limité ?

Il n’existe aucune limite spécifique au nombre d’URL signées que vous pouvez générer.

#### Comment les listes d’autorisation gèrent-elles les sous-domaines ?

Les listes d’autorisation effectuent une correspondance exacte sur les noms d’hôte. Si vous souhaitez autoriser à la fois un domaine et ses sous-domaines, vous devez les ajouter séparément, par exemple « example.com » et « app.example.com ».

#### Dois-je utiliser les deux méthodes d’authentification ?

Non. Configurez soit des URL signées, soit une liste d’autorisation pour chaque agent. Pour les applications côté client, les URL signées sont l’option recommandée par défaut.

#### Quelles autres mesures de sécurité dois-je mettre en œuvre ?

En plus des URL signées et des listes d’autorisation, envisagez de mettre en œuvre :

* Une authentification utilisateur avant de demander des URL signées
* Une limitation du débit des requêtes API
* Un suivi de l’utilisation afin de détecter des schémas suspects
* Une gestion appropriée des erreurs d’authentification