Obtenir un jeton d'accès
Échangez votre clé d'API contre un jeton porteur à courte durée de vie — le premier appel de toute intégration avec l'API de signature électronique.
Toute intégration avec l'API de signature électronique commence ici. Vous envoyez votre clé d'API une seule fois à cet endpoint et recevez un jeton d'accès à courte durée de vie. Ensuite, toutes les autres requêtes ne transportent que le jeton : votre clé ne circule plus.
Endpoint
POST https://api2.bunnydoc.com/v1/auth/token
Requête
La clé est envoyée dans un en-tête. Il n'y a pas de corps de requête.
| En-tête | Requis | Valeur |
|---|---|---|
X-API-Key | Oui | Votre clé d'API, p. ex. bd_live_a1b2c3d4e5f6…. Créez-en une dans Paramètres → Clés d'API. |
Exemple de requête
curl -X POST https://api2.bunnydoc.com/v1/auth/token \
-H "X-API-Key: bd_live_a1b2c3d4e5f6g7h8"POST /v1/auth/token HTTP/1.1
Host: api2.bunnydoc.com
X-API-Key: bd_live_a1b2c3d4e5f6g7h8const res = await fetch("https://api2.bunnydoc.com/v1/auth/token", {
method: "POST",
headers: { "X-API-Key": process.env.BUNNYDOC_API_KEY },
});
const { access_token, expires_in } = await res.json();
// Cache access_token and reuse it for the next `expires_in` seconds.import os, requests
res = requests.post(
"https://api2.bunnydoc.com/v1/auth/token",
headers={"X-API-Key": os.environ["BUNNYDOC_API_KEY"]},
)
token = res.json()["access_token"]
# Cache the token and reuse it until it expires.Réponse
Un 200 OK renvoie le jeton et les scopes qu'il porte.
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlfaWQiOiI…",
"token_type": "Bearer",
"expires_in": 3600,
"scopes": ["templates:read", "envelopes:send", "webhooks:read", "webhooks:write"]
}| Champ | Type | Description |
|---|---|---|
access_token | string | Le jeton porteur. Envoyez-le en Authorization: Bearer <access_token> sur toutes les autres requêtes. |
token_type | string | Toujours Bearer. |
expires_in | integer | Nombre de secondes avant l'expiration du jeton — toujours 3600 (une heure). |
scopes | string[] | Les permissions portées par ce jeton, héritées de la clé. |
Utiliser le jeton
Envoyez le jeton dans l'en-tête Authorization sur tous les autres appels. Par exemple, pour lister
vos modèles :
curl https://api2.bunnydoc.com/v1/templates \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"Erreurs
Toutes les erreurs ont la même forme : basez-vous sur error.code, jamais sur le texte du message.
{
"error": {
"code": "invalid_api_key",
"message": "The API key is invalid, revoked, expired, or not a live-mode key."
}
}| Statut | error.code | Quand cela se produit |
|---|---|---|
401 | missing_api_key | Aucun en-tête X-API-Key n'a été envoyé. |
401 | invalid_api_key | La clé est inconnue, révoquée, expirée ou n'est pas de mode réel. Les quatre renvoient le même corps : nous ne révélons pas lequel. |
403 | forbidden | L'accès à l'API n'est pas inclus dans le plan actuel de votre entreprise. |
429 | rate_limited | Plus de 20 requêtes de jeton en 15 minutes depuis une IP. Demandez un jeton par heure, pas un par appel. |
Consultez la référence des erreurs complète, avec tous les codes que l'API peut renvoyer.
Bon à savoir
Les jetons durent une heure — mettez-les en cache et réutilisez-les
expires_in vaut toujours 3600 secondes. Demandez un jeton, conservez-le et n'échangez votre clé à
nouveau que lorsque le jeton est proche de l'expiration. L'endpoint d'échange de jeton est limité à
20 requêtes par 15 minutes par IP précisément parce qu'une intégration saine a besoin d'environ un
jeton par heure, pas d'un par requête.
Révoquer une clé invalide ses jetons immédiatement
Nul besoin d'attendre l'expiration d'un jeton. Dès qu'une clé est révoquée dans
Paramètres → Clés d'API, tous les jetons issus d'elle cessent de fonctionner à leur requête
suivante, avec 401 key_revoked.
Le renouvellement est différent : l'ancienne clé ne peut plus être échangée contre un jeton, mais les jetons déjà émis à partir d'elle restent valables jusqu'à leur expiration (jusqu'à une heure). Cela fait du renouvellement un relais propre pour un déploiement — et le mauvais outil en cas de fuite, où il faut révoquer.
Étapes suivantes
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.
Modèles
Listez vos modèles de signature électronique et lisez les rôles d'un modèle précis — le point de départ pour envoyer une enveloppe depuis l'API.