> For the complete documentation index, see [llms.txt](https://boundaryai.gitbook.io/boundaryai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boundaryai.gitbook.io/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/authentication.md).

# Authentification et clés API

Clés API, périmètres d'autorisation, environnements et limites de débit.

Chaque appel API s'authentifie avec une **clé API** transmise sous forme de jeton Bearer :

```
Authorization: Bearer inpk_live_...
```

Il n'y a pas de cookies de session sur l'API : une clé, un en-tête. Les fonctionnalités du tableau de bord (création d'enquêtes, gestion des membres, paramètres de l'organisation) ne sont pas accessibles avec une clé API par conception. Le seul endroit où un accès basé sur la connexion existe est le flux de connexion de l'assistant IA, qui utilise OAuth au lieu d'une clé ; voir [Connecter les assistants IA](/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/mcp.md).

***

### Créer et gérer des clés

Les clés se trouvent dans le tableau de bord, sous **Intégrations → Outils développeur → Clés API** (administrateur uniquement). Chaque clé comporte :

* Un **libellé**, afin de distinguer votre synchronisation CRM de votre export d'entrepôt de données.
* Un **environnement**: `inpk_live_*` pour le trafic de production, `inpk_test_*` pour les intégrations de préproduction. Elles se comportent de manière identique ; cette séparation existe pour que vous puissiez révoquer la préproduction sans toucher à la production. Les clés de test ne sont jamais facturées en utilisation.
* Un **portée d'autorisation** (ci-dessous).
* Un **limite de débit par clé**, 60 requêtes/minute par défaut, ajustable entre 1 et 300 à la création ou ultérieurement.
* **Statistiques d'utilisation par clé**, y compris les codes de statut réels des réponses, afin que vous puissiez repérer une intégration défaillante depuis le tableau de bord.

Le secret est affiché **une seule fois** à la création. Conservez-le comme un mot de passe ; faites-le pivoter depuis le même écran s'il fuit ou lorsqu'un coéquipier ayant accès quitte l'équipe.

***

### Portées d'autorisation

Définissez la portée de ce que chaque intégration peut faire ; ne remettez pas une `all` clé à chaque système.

| Portée     | Ce que cela permet                                                                                                                                                                                                                                    |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `push`     | Envoyer des retours vers des sources existantes, ainsi que tout ce qu'implique push : statuts en masse, téléversement de fichiers, liste et suppression des retours, lectures d'analyse.                                                              |
| `create`   | Tout `push` peut, plus la création et la publication de sources avec leurs champs au sein des groupes de retours existants.                                                                                                                           |
| `send`     | Déclencher les e-mails d'invitation à l'enquête ([Envoi des invitations](/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/sending-invites.md)). Délibérément séparé : envoyer des e-mails à des humains est plus important que l'envoi de données. |
| `mcp_read` | Accès en lecture seule pour le point de terminaison MCP, afin qu'un assistant IA puisse interroger les analyses mais jamais écrire. Voir [Connecter les assistants IA](/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/mcp.md).                   |
| `all`      | Tout ce qui précède, plus la création de groupes de retours (`POST /feedback_groups/create`), ce qu'aucun périmètre plus restreint ne peut faire.                                                                                                     |

Chaque opération d'écriture dans la référence de l'API indique la portée requise. Un appel en dehors de la portée de la clé renvoie **403** avec le code `INSUFFICIENT_PERMISSION`.

{% hint style="info" %}
`send` est en outre conditionné par un **domaine d'envoi vérifié**: les envois API n'empruntent jamais l'expéditeur partagé de BAI Analytics, de sorte que les envois automatisés reposent sur votre propre réputation d'envoi. Voir [Envoi des invitations](/boundaryai-docs/boundaryai-docs-fr/importer-vos-retours/surveys/managing-surveys.md#sending-invites).
{% endhint %}

{% hint style="info" %}
`mcp_read` les clés sont **liées à la personne qui les a créées**. À chaque requête MCP, la plateforme vérifie à nouveau que cette personne a toujours un compte actif et est toujours membre de l'organisation ; sinon, la clé cesse immédiatement de fonctionner (403 `MCP_KEY_UNBOUND`) et s'affiche comme arrêtée dans le tableau de bord. Les clés d'intégration (`push`, `create`, `send`, `all`) sont des clés d'organisation et survivent à leur créateur, de sorte qu'un pipeline ETL continue de s'exécuter après le départ de l'ingénieur qui l'a mis en place.
{% endhint %}

***

### Introspection : `GET /me`

Une intégration peut découvrir ses propres capacités sans accès au tableau de bord :

```bash
curl https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/me \\
  -H "Authorization: Bearer $BAI_API_KEY"
```

La réponse inclut le nom de la clé, l'environnement et les autorisations, l'identifiant de l'organisation et `org_name` (pratique comme libellé d'une connexion enregistrée), le **limites de débit effectives**, l'état d'utilisation de l'organisation sous `crédits`, et les **types d'événements de webhook** disponibles à l'abonnement. Cela ne coûte rien, ce qui en fait aussi la bonne cible pour les tests de connexion.

***

### Limites de débit

Valeurs par défaut : **60 requêtes/minute par clé**, **300 requêtes/minute par organisation**, et 600 par minute par adresse IP. Les fenêtres sont des fenêtres fixes de 60 secondes ancrées à la première requête : une requête rejetée avec 429 ne prolonge pas l'attente, donc `Retry-After` est exact. Les chiffres de votre clé se trouvent dans `GET /me`; la limite par clé peut être portée jusqu'à 300 lors de la création ou de la modification de la clé.

Lorsque vous atteignez une limite, l'API renvoie **429** avec un `Retry-After` en-tête, et chaque réponse comporte `X-RateLimit-Limit`, `X-RateLimit-Remaining`, et `X-RateLimit-Reset`. Ralentissez et réessayez ; pour un volume soutenu, privilégiez les points de terminaison en masse (un appel pour des milliers d'éléments) plutôt que les appels par élément.

***

### Enveloppe de réponse

Aujourd'hui, les réponses 2xx transportent directement la charge utile, comme indiqué dans chaque exemple de la référence, ainsi que `Deprecation` et `Sunset` des en-têtes. Ces en-têtes n'annoncent qu'une seule chose : après la date de fin de vie, les charges utiles de succès seront encapsulées comme `{"data": {...}}`, comme les schémas le déclarent déjà. Aucun point de terminaison n'est en cours de dépréciation. Les erreurs sont toujours `{"error": {"code": "...", "message": "..."}}` avec un `details` objet.

***

### Bonnes pratiques

* **Une clé par intégration.** Révoquer un système compromis ne devrait pas faire tomber les autres.
* **Réduisez la portée.** Une synchronisation CRM a besoin de `push`, pas de `all`.
* **Utilisez `Idempotency-Key` sur les écritures.** Tout push peut être relancé en toute sécurité dans les 24 heures.
* **Faites tourner lors des changements de personnel.** Même politique que pour les mots de passe.