Authentification

L’API authentifie les serveurs au moyen de clés API d’organisation. Une clé appartient à une organisation (et non à une personne), porte un ensemble d’autorisations et fonctionne dans un seul mode : test ou production.

Envoyer la clé

Utilisez l’un ou l’autre de ces en-têtes :

# Authorization header (recommended)
curl https://api.bonafidesign.com/v1/envelopes -H "Authorization: Bearer bf_live_…"

# or x-api-key
curl https://api.bonafidesign.com/v1/envelopes -H "x-api-key: bf_live_…"

Les clés ont la forme bf_live_… ou bf_test_…. Une clé absente donne un 401 (unauthorized) ; une clé mal formée, révoquée ou expirée donne également un 401. Conservez les clés sur votre serveur : ne les livrez jamais à un navigateur ni à une application mobile. Pour signer dans le navigateur, créez plutôt une session de signature.

Clés de test et de production

	Test (`bf_test_…`)	Production (`bf_live_…`)
Documents	Générés avec un filigrane `TEST`	Sans filigrane
E-mail	Remis uniquement aux membres de votre organisation	Remis à chaque destinataire
Facturation	Gratuit et illimité, jamais décompté	Les enveloppes finalisées sont décomptées de votre forfait
Données	Les enveloppes, liens et endpoints de webhook créés avec la clé sont en mode test	Mode production

Le mode dépend de la clé, jamais de la requête : ?test_mode=true sur POST /v1/envelopes ne s’applique qu’aux sessions du tableau de bord. Les listes (GET /v1/envelopes, GET /v1/signing-links) ne renvoient que le mode de la clé, et les événements d’une enveloppe ne sont envoyés qu’aux endpoints de webhook du même mode. Chaque enveloppe et chaque charge utile de webhook indique son mode (testMode).

Créer et révoquer des clés

Les clés se gèrent dans le tableau de bord, sous Paramètres › Clés API, par les membres disposant de l’autorisation apikey:manage (propriétaires et administrateurs). Le secret n’est affiché qu’une seule fois, à la création de la clé. Vous pouvez attribuer à une clé un nom, un mode, une date d’expiration (de 1 à 365 jours, ou aucune) et des portées.

Portées

Les portées d’une clé sont les autorisations de l’organisation qu’elle peut utiliser. Par défaut, une nouvelle clé reçoit les autorisations de son créateur, moins les autorisations d’administration (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), et personne ne peut accorder à une clé une autorisation qu’il ne possède pas lui-même. Un appel en dehors des portées de la clé renvoie un 403 qui nomme l’autorisation manquante :

{
  "type": "https://bonafidesign.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: envelope:send.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Autorisation	Permet à une clé de
`template:read`	Lister et lire les modèles, leurs versions et leurs PDF
`template:write`	Créer des modèles, importer des fichiers, enregistrer des brouillons, supprimer des modèles inutilisés
`template:publish`	Publier un brouillon sous forme de nouvelle version
`envelope:read`	Lister et lire les enveloppes, les documents et les pistes d’audit ; lister les liens de signature
`envelope:send`	Créer des enveloppes, des sessions de signature et des liens de signature ; renvoyer des liens
`envelope:void`	Annuler des enveloppes en cours
`org:manage`	Gérer les endpoints de webhook et relivrer des événements ; lire les paramètres de l’organisation
`billing:manage`	Lire la consommation (`GET /v1/usage`) et les montants des factures

La gestion des endpoints de webhook exige org:manage, que les clés ne reçoivent pas par défaut : enregistrez les endpoints dans le tableau de bord, ou créez explicitement une clé dotée de cette portée.

Quels endpoints acceptent quoi

Chaque opération de la référence de l’API indique ses schémas de sécurité. En résumé :

Clé API ou session du tableau de bord : modèles, enveloppes, sessions de signature, liens de signature, endpoints de webhook, paramètres de l’organisation, aperçu de la facturation et consommation.
Session du tableau de bord uniquement : clés API, jetons SCIM, paramètres de connexion SSO, import du logo de l’organisation, paiement et portail de facturation, affichage d’un secret de webhook.
Jeton de signataire : /v1/signing/*, utilisé par la page hébergée et par <bf-signing> avec un jeton de session (bfs_…) ou le jeton d’accès obtenu en échange (bfa_…).
Public : /v1/links/{id} (liens permanents), /v1/sso/discover et l’API de vérification (/v1/public/*, /.well-known/bona-fide/keys.json).

Se connecter au tableau de bord

Les personnes (et non les serveurs) se connectent au tableau de bord sur https://app.bonafidesign.com/sign-in. Par défaut, la connexion se fait avec une adresse e-mail et un mot de passe ; les alternatives sont un code à six chiffres envoyé par e-mail (Recevoir plutôt un code par e-mail), un lien magique, une passkey, Google ou Microsoft, et le SSO de votre entreprise.

La création d’un compte avec mot de passe déclenche l’envoi d’un e-mail : un code qui confirme que l’adresse vous appartient. D’ici là, le mot de passe ne permet pas de se connecter. Une inscription avec une adresse déjà associée à un compte ne modifie rien et reçoit exactement la même réponse qu’une nouvelle inscription ; le titulaire de l’adresse reçoit un e-mail qui lui explique comment se connecter.
Les mots de passe comportent de 12 à 128 caractères et sont stockés sous forme de hachages scrypt salés. Un nouveau mot de passe qui figure dans une fuite de données connue est refusé : seuls les cinq premiers caractères de son hachage SHA-1 sont envoyés à Have I Been Pwned (k-anonymat), jamais le mot de passe lui-même. Si ce service ne répond pas dans les deux secondes, le mot de passe est accepté sans vérification.
Mot de passe oublié ? L’e-mail de réinitialisation renvoie vers une page où vous en choisissez un nouveau. Le lien ne fonctionne qu’une fois, expire au bout d’une heure, et son utilisation vous déconnecte sur tous vos appareils.
Pas encore de mot de passe ? Les comptes créés avec un code, un lien, une passkey ou Google / Microsoft continuent de se connecter ainsi et peuvent ajouter un mot de passe dans Paramètres › Compte. Définir un premier mot de passe exige une connexion datant de moins de 15 minutes (la page vous envoie un code par e-mail pour confirmer votre identité) ; pour le modifier, il faut le mot de passe actuel. Dans les deux cas, vos autres sessions sont déconnectées.
Les erreurs ne révèlent jamais l’existence d’un compte : un mot de passe erroné, une adresse inconnue et un compte sans mot de passe reçoivent la même réponse, et une demande de réinitialisation indique toujours que l’e-mail est en route.
Limites de débit : la connexion par mot de passe, l’inscription et les demandes de réinitialisation sont limitées par adresse IP et par adresse e-mail ; au-delà de la limite, la réponse est 429 jusqu’à la fin de la fenêtre.
SSO d’entreprise : lorsque votre organisation impose le SSO, les membres dont l’adresse appartient à ses domaines se connectent uniquement via le fournisseur d’identité. Les mots de passe, codes et liens magiques sont refusés pour eux ; les propriétaires conservent le code par e-mail comme accès de secours.

Identifiants de requête

Chaque réponse comporte un en-tête x-request-id, et chaque corps d’erreur un requestId. Vous pouvez envoyer votre propre x-request-id (de 8 à 128 caractères parmi A-Z a-z 0-9 . _ -) pour corréler vos journaux ; sinon, l’API en génère un. Communiquez-le lorsque vous contactez le support.