Authentification

L’API authentifie les serveurs au moyen de clés d’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é manquante donne une erreur 401 (unauthorized); une clé mal formée, révoquée ou expirée donne aussi une 401. Gardez vos clés sur votre serveur : ne les intégrez 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 le filigrane `TEST`	Sans filigrane
Courriels	Livrés uniquement aux membres de votre organisation	Livrés à tous les destinataires
Facturation	Gratuit et illimité, jamais comptabilisé	Les enveloppes finalisées sont comptabilisées dans votre forfait
Données	Les enveloppes, liens et points de terminaison de webhook créés avec la clé sont en mode test	En 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 transmis qu’aux points de terminaison 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 d’API, par les membres qui détiennent 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 donner à 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 la personne qui la crée, 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 détient pas lui-même. Un appel hors des portées de la clé donne une erreur 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, téléverser des fichiers, enregistrer des brouillons, supprimer des modèles inutilisés
`template:publish`	Publier un brouillon comme 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 points de terminaison de webhook et relivrer des événements; lire les paramètres de l’organisation
`billing:manage`	Lire l’utilisation (`GET /v1/usage`) et les montants des factures

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

Ce qu’accepte chaque point de terminaison

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

Clé d’API ou session du tableau de bord : modèles, enveloppes, sessions de signature, liens de signature, points de terminaison de webhook, paramètres de l’organisation, aperçu de la facturation et utilisation.
Session du tableau de bord seulement : clés d’API, jetons SCIM, paramètres de connexion SSO, téléversement 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).

Connexion au tableau de bord

Les personnes (et non les serveurs) se connectent au tableau de bord à l’adresse https://app.bonafidesign.com/sign-in. Par défaut, on se connecte avec une adresse courriel et un mot de passe; les autres options sont un code à six chiffres envoyé par courriel (M’envoyer plutôt un code par courriel), un lien magique, une clé d’accès, 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 courriel : un code qui confirme que l’adresse vous appartient. D’ici là, le mot de passe ne permet pas de se connecter. S’inscrire avec une adresse déjà associée à un compte ne change rien et produit exactement la même réponse qu’une nouvelle inscription; le titulaire de l’adresse reçoit plutôt un courriel qui lui explique comment se connecter.
Les mots de passe comptent 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. Si ce service ne répond pas dans un délai de deux secondes, le mot de passe est accepté sans vérification.
Mot de passe oublié? Le courriel de réinitialisation renvoie à une page où vous en choisissez un nouveau. Le lien ne fonctionne qu’une fois et expire au bout d’une heure; 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 clé d’accès ou Google / Microsoft continuent de se connecter de cette façon, et peuvent ajouter un mot de passe dans Paramètres › Compte. Définir un premier mot de passe exige une connexion dans les 15 dernières minutes (la page vous envoie un code par courriel pour confirmer qu’il s’agit bien de vous); le modifier exige 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 mauvais mot de passe, une adresse inconnue et un compte sans mot de passe obtiennent la même réponse, et une demande de réinitialisation indique toujours que le courriel est en route.
Limites de débit : les connexions par mot de passe, les inscriptions et les demandes de réinitialisation sont limitées par adresse IP et par adresse courriel; 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 de ses domaines de courriel se connectent uniquement par le fournisseur d’identité. Les mots de passe, les codes et les liens magiques leur sont refusés; les propriétaires conservent le code par courriel comme accès d’urgence.

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 faire le lien avec vos journaux; sinon, l’API en génère un. Indiquez-le quand vous communiquez avec le soutien.