> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bookivox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connexion et authentification

> Authentifier vos requêtes, choisir une surface (API REST ou MCP) et configurer les webhooks.

L'API Bookivox est une API **server-to-server**. Toutes les requêtes passent par le préfixe `/api/v1/api` et s'authentifient avec une **clé API**.

> [!NOTE]
>
> Les clés API doivent rester **côté serveur**. Ne les embarquez jamais dans du code client (navigateur, application mobile) ni dans un dépôt public.

## Authentification

Ajoutez votre clé dans l'en-tête `X-API-Key`.

**cURL**

```bash theme={null}
curl https://api.bookivox.com/api/v1/api/workflow/fetch \
  -H "X-API-Key: bookeys_xxxxxxxxxxxxxxxxxxxx"
```

**JavaScript**

```javascript theme={null}
const res = await fetch("https://api.bookivox.com/api/v1/api/workflow/fetch", {
  headers: { "X-API-Key": process.env.BOOKIVOX_API_KEY }
});
const agents = await res.json();
```

**Python**

```python theme={null}
import os, requests

res = requests.get(
    "https://api.bookivox.com/api/v1/api/workflow/fetch",
    headers={"X-API-Key": os.environ["BOOKIVOX_API_KEY"]},
)
agents = res.json()
```

> [!WARNING]
>
> L'en-tête `Authorization` est **interdit** sur cette surface : sa présence renvoie `400`. Utilisez uniquement `X-API-Key`.

## Créer une clé API

1. Ouvrez **Workspace → Clés API** dans le dashboard.
2. Créez une clé avec un nom parlant (ex. « Backend production »).
3. Copiez la valeur immédiatement : elle n'est affichée **qu'une seule fois**.

Une clé donne accès à toute l'organisation. Pour cloisonner, créez une clé par environnement de votre application.

## Surfaces disponibles

**API REST**

Appels HTTP classiques décrits dans cette référence. Idéal pour automatiser la création d'agents, lancer des campagnes ou interroger votre base de connaissance depuis votre backend.

* **Base URL** : `https://api.bookivox.com/api/v1/api`
* **Auth** : en-tête `X-API-Key`

**Serveur MCP**

Connectez Claude, Cursor ou VS Code à Bookivox via le Model Context Protocol. Vous pilotez vos agents en langage naturel, depuis votre outil d'IA, avec la même clé API.

> **[Configurer le serveur MCP](https://docs.bookivox.com/mcp/overview.md)**
>
> Guide de connexion, capacités exposées et bonnes pratiques de sécurité.

## Webhooks

Deux directions existent, à ne pas confondre.

> **Bookivox → votre serveur**
>
> Le nœud **Webhook** d'un agent envoie une requête HTTP vers une URL de votre choix pendant ou après l'appel. Vous recevez les données de l'appel (transcription, résumé, variables collectées) et pouvez déclencher vos propres traitements.
>
> > **[Nœud Webhook](https://docs.bookivox.com/workflow/nodes/webhook.md)**
> >
> > Champs, variables de template, cas d'usage et sécurité.

> **Votre serveur → Bookivox (outil HTTP)**
>
> Vous exposez un endpoint que l'agent appelle pendant l'appel (vérifier une disponibilité, créer un rendez-vous…). Bookivox appelle votre API avec les paramètres définis.
>
> > **[Outil HTTP API](https://docs.bookivox.com/integrations/http-api.md)**
> >
> > Configuration complète d'un outil HTTP.

> [!TIP]
>
> Les endpoints sortants vers votre serveur doivent être **idempotents** : un même événement peut être livré plusieurs fois. Utilisez un identifiant d'événement pour dédupliquer.

## Étapes suivantes

> **[Démarrage rapide](https://docs.bookivox.com/api-reference/quickstart)**
>
> Votre première requête en quelques minutes.

> **[Codes d'erreur](https://docs.bookivox.com/api-reference/errors)**
>
> Comprendre et gérer les réponses d'erreur.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.