Créer et gérer des clés d'API

Créez une clé d'API, choisissez ses scopes, définissez une expiration, puis renouvelez-la ou révoquez-la — tout ce qu'il faut avant votre premier appel.

Une clé d'API est l'identifiant de longue durée derrière chaque intégration. Vous ne l'envoyez jamais sur les requêtes ordinaires : vous l'échangez une seule fois contre un jeton d'accès de courte durée, et c'est le jeton qui travaille.

Les clés se gèrent dans l'application, pas via l'API — il n'existe volontairement aucun endpoint qui crée un identifiant.

Où

Paramètres → Clés d'API. Visible uniquement par les propriétaires et administrateurs, et seulement si votre offre inclut l'accès à l'API.

Avant de commencer : l'accès à l'API est-il dans votre offre ?

L'accès à l'API est vendu séparément du reste de BunnyDoc. Sans lui :

l'écran Clés d'API refuse de créer une clé, et
POST /v1/auth/token renvoie 403 forbidden, même pour une clé qui existe déjà.

Cherchez deux entrées dans Paramètres → Facturation → Ressources :

Ressource	Ce qu'elle contrôle
Accès API	Si `/v1` fonctionne du tout, et si vous pouvez créer des clés.
Demandes de signature API	Combien d'enveloppes vous pouvez envoyer via l'API par période — une unité par enveloppe.

Si l'une manque ou est à zéro, parlons-en avant que vous ne développiez.

Créer une clé

Nommez-la d'après l'intégration, pas d'après la personne

Zapier — production, Synchro facturation, Bac à sable. Le nom est ce qui vous permettra de la reconnaître lors d'un renouvellement ou d'une révocation des mois plus tard, et c'est tout ce que vous aurez : la clé elle-même n'est plus jamais affichée.

Choisissez le jeu de scopes le plus restreint

Les scopes sont définis par clé. N'accordez que ce que l'intégration appelle — voir le tableau ci-dessous.

Définissez éventuellement une expiration

Laissez vide et la clé n'expire jamais. Indiquez une date future et la clé cesse de fonctionner à ce moment-là, en renvoyant le même 401 qu'une clé inconnue. Une expiration est une bonne hygiène pour une clé confiée à un tiers ou utilisée pour une migration limitée dans le temps.

Copiez la clé immédiatement

La clé ressemble à bd_live_… et n'est affichée qu'une seule fois, à la création. Elle est stockée hachée chez nous : nous ne pouvons donc pas vous la remontrer. Si vous la perdez, renouvelez la clé pour obtenir un nouveau secret.

Gardez la clé côté serveur

Une clé agit au nom de toute votre entreprise. Ne la placez jamais dans un navigateur, une application mobile, un dépôt de code ou un client que vous ne maîtrisez pas. Chargez-la depuis une variable d'environnement ou un gestionnaire de secrets.

Scopes

Un scope autorise une clé à faire quelque chose. Il ne peut jamais lui permettre de faire plus que la personne qui l'a créée : les deux sont croisés à chaque requête, donc si cette personne perd une permission dans l'app, ses clés la perdent au même instant.

Scope	Débloque
`templates:read`	`GET /v1/templates`, `GET /v1/templates/{id}`
`contacts:read`	`GET /v1/contacts`
`contacts:write`	`POST /v1/contacts`
`envelopes:send`	`POST /v1/envelopes/from-template`, `GET /v1/envelopes/{id}/signing-links`
`webhooks:read`	`GET /v1/webhooks`, `GET /v1/webhooks/events`
`webhooks:write`	`POST /v1/webhooks`, `DELETE /v1/webhooks/{id}`
`users:read`	`GET /v1/users`

Chaque clé a besoin d'au moins un scope. Une intégration classique « envoyer et suivre » a besoin de templates:read, envelopes:send, webhooks:read et webhooks:write — et de rien d'autre.

Deux contrôles indépendants

Appeler un endpoint exige à la fois le scope sur la clé et la permission correspondante chez son propriétaire. Une clé avec templates:read dont le propriétaire ne peut pas lire les modèles dans l'app reçoit 403 forbidden, pas un résultat. Un scope manquant donne 403 insufficient_scope : les deux échecs sont donc faciles à distinguer.

Combien de clés puis-je avoir ?

Votre offre fixe le nombre de clés actives par entreprise. Une fois la limite atteinte, la création est refusée jusqu'à ce que vous en révoquiez une. Les clés révoquées ne comptent pas.

Utilisez des clés distinctes par environnement et par intégration : c'est le seul moyen de révoquer une chose sans casser le reste.

Renouveler une clé

Le renouvellement émet un nouveau secret sur le même enregistrement de clé, en conservant son nom, ses scopes et son expiration. Utilisez-le pour une hygiène d'identifiants planifiée.

Le renouvellement est irréversible :

la nouvelle clé est affichée une seule fois — copiez-la, puis déployez-la ;
l'ancien secret ne peut plus être échangé contre un jeton, donc POST /v1/auth/token avec lui renvoie 401 invalid_api_key ;
les jetons d'accès déjà émis à partir de l'ancien secret continuent de fonctionner jusqu'à leur expiration — jusqu'à une heure.

Un renouvellement est donc un relais propre pour votre propre déploiement : terminez le déploiement dans l'heure et aucune requête n'échoue.

Si une clé a fuité, révoquez-la — ne vous contentez pas de la renouveler

Le renouvellement ferme la porte aux nouveaux jetons mais laisse valable tout jeton déjà émis à partir de l'ancien secret pour le reste de son heure. Pour couper l'accès immédiatement, révoquez la clé et créez-en une nouvelle.

Révoquer une clé

La révocation neutralise la clé définitivement, et c'est l'action qui prend effet immédiatement :

la clé ne peut plus jamais être échangée contre un jeton, et
tous les jetons en cours émis à partir d'elle échouent à leur requête suivante, avec 401 key_revoked — sans attendre la fin de leur heure.

C'est la bonne réponse à une fuite suspectée, au départ d'un prestataire, ou à une intégration que vous arrêtez.

Ce que votre intégration doit faire face aux erreurs de clé

Vous obtenez	Ce qui s'est passé	Faites ceci
`401 invalid_api_key` sur `/auth/token`	La clé est inconnue, révoquée, expirée ou hors mode réel — nous ne précisons pas	Arrêtez de réessayer. Vérifiez la clé dans Paramètres → Clés d'API.
`403 forbidden` sur `/auth/token`	L'accès à l'API n'est pas dans l'offre	Arrêtez de réessayer. C'est un changement de facturation, pas de code.
`401 invalid_token` sur tout autre appel	Le jeton a expiré	Échangez la clé contre un nouveau jeton et réessayez une fois.
`401 key_revoked` sur tout autre appel	La clé derrière le jeton a été révoquée	Arrêtez de réessayer avec le jeton en cache. Chargez la clé de remplacement.
`403 insufficient_scope`	La clé manque d'un scope	Ajoutez le scope à la clé (ou créez-en une qui l'a).

Ne créez pas un jeton par requête

POST /v1/auth/token est plafonné à 20 requêtes toutes les 15 minutes, par IP, car une intégration saine a besoin d'environ un jeton par heure. Mettez le jeton en cache pour tout son expires_in et renouvelez-le peu avant qu'il n'expire.