Authentifizierung

Die API authentifiziert Server mit API-Schlüsseln der Organisation. Ein Schlüssel gehört einer Organisation (nicht einer Person), hat eine Reihe von Berechtigungen und funktioniert in genau einem Modus: Test oder Live.

Schlüssel senden

Verwenden Sie einen der beiden Header:

# 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_…"

Schlüssel haben die Form bf_live_… oder bf_test_…. Ein fehlender Schlüssel ergibt 401 (unauthorized); ein fehlerhafter, widerrufener oder abgelaufener Schlüssel ebenfalls 401. Bewahren Sie Schlüssel auf Ihrem Server auf: Liefern Sie sie nie an einen Browser oder eine mobile App aus. Für das Unterschreiben im Browser erzeugen Sie stattdessen eine Signatursitzung.

Test- und Live-Schlüssel

	Test (`bf_test_…`)	Live (`bf_live_…`)
Dokumente	Mit Wasserzeichen `TEST` gerendert	Ohne Wasserzeichen
E-Mail	Nur an Mitglieder Ihrer Organisation zugestellt	An jeden Empfänger zugestellt
Abrechnung	Kostenlos und unbegrenzt, wird nie gezählt	Abgeschlossene Umschläge werden auf Ihren Tarif angerechnet
Daten	Mit dem Schlüssel erstellte Umschläge, Links und Webhook-Endpunkte sind im Testmodus	Live-Modus

Der Modus ergibt sich aus dem Schlüssel, nie aus der Anfrage: ?test_mode=true bei POST /v1/envelopes gilt nur für Dashboard-Sitzungen. Listen (GET /v1/envelopes, GET /v1/signing-links) liefern nur den Modus des Schlüssels, und die Events eines Umschlags gehen nur an Webhook-Endpunkte desselben Modus. Jeder Umschlag und jede Webhook-Nutzlast gibt an, in welchem Modus sie sich befinden (testMode).

Schlüssel erstellen und widerrufen

Schlüssel werden im Dashboard unter Einstellungen › API-Schlüssel verwaltet, und zwar von Mitgliedern mit der Berechtigung apikey:manage (Inhaber und Admins). Das Secret wird einmal angezeigt, beim Erstellen des Schlüssels. Sie können einem Schlüssel einen Namen, einen Modus, ein Ablaufdatum (1 bis 365 Tage oder keines) und Scopes geben.

Scopes

Die Scopes eines Schlüssels sind die Berechtigungen der Organisation, die er nutzen darf. Standardmäßig erhält ein neuer Schlüssel die Berechtigungen seines Erstellers ohne die administrativen (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), und niemand kann einem Schlüssel eine Berechtigung geben, die er selbst nicht hat. Ein Aufruf außerhalb der Scopes des Schlüssels ergibt 403 mit der fehlenden Berechtigung:

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

Berechtigung	Erlaubt einem Schlüssel
`template:read`	Vorlagen, Versionen und deren PDFs auflisten und lesen
`template:write`	Vorlagen erstellen, Dateien hochladen, Entwürfe speichern, ungenutzte Vorlagen löschen
`template:publish`	Einen Entwurf als neue Version veröffentlichen
`envelope:read`	Umschläge, Dokumente und Audit-Trails auflisten und lesen; Signaturlinks auflisten
`envelope:send`	Umschläge, Signatursitzungen und Signaturlinks erstellen; Links erneut senden
`envelope:void`	Laufende Umschläge stornieren
`org:manage`	Webhook-Endpunkte verwalten und Events erneut zustellen; Organisationseinstellungen lesen
`billing:manage`	Nutzung (`GET /v1/usage`) und Rechnungsbeträge lesen

Zum Verwalten von Webhook-Endpunkten ist org:manage nötig, das Schlüssel standardmäßig nicht erhalten: Registrieren Sie Endpunkte im Dashboard oder erstellen Sie ausdrücklich einen Schlüssel mit diesem Scope.

Welche Endpunkte was akzeptieren

Jede Operation in der API-Referenz nennt ihre Sicherheitsschemata. Kurz gefasst:

API-Schlüssel oder Dashboard-Sitzung: Vorlagen, Umschläge, Signatursitzungen, Signaturlinks, Webhook-Endpunkte, Organisationseinstellungen, Abrechnungsübersicht und Nutzung.
Nur Dashboard-Sitzung: API-Schlüssel, SCIM-Tokens, SSO-Verbindungseinstellungen, Hochladen des Organisationslogos, Checkout und Portal der Abrechnung, Anzeigen eines Webhook-Secrets.
Unterzeichner-Token: /v1/signing/*, verwendet von der gehosteten Seite und von <bf-signing> mit einem Sitzungstoken (bfs_…) oder dem Zugriffstoken, gegen das es eingetauscht wird (bfa_…).
Öffentlich: /v1/links/{id} (dauerhafte Links), /v1/sso/discover und die Verifizierungs-API (/v1/public/*, /.well-known/bona-fide/keys.json).

Anmeldung im Dashboard

Personen (nicht Server) melden sich unter https://app.bonafidesign.com/sign-in im Dashboard an. Standard ist E-Mail-Adresse und Passwort; alternativ gibt es einen per E-Mail gesendeten sechsstelligen Code (Stattdessen Code per E-Mail senden), einen Magic Link, einen Passkey, Google oder Microsoft und das SSO Ihres Unternehmens.

Beim Erstellen eines Kontos mit Passwort wird eine E-Mail gesendet: ein Code, der bestätigt, dass die Adresse Ihnen gehört. Bis dahin meldet das Passwort Sie nicht an. Eine Registrierung mit einer Adresse, für die bereits ein Konto besteht, ändert nichts und wird genau wie eine neue Registrierung beantwortet; der Inhaber der Adresse erhält eine E-Mail, die erklärt, wie er sich stattdessen anmeldet.
Passwörter sind 12 bis 128 Zeichen lang und werden als gesalzene scrypt-Hashes gespeichert. Ein neues Passwort, das in einem bekannten Datenleck vorkommt, wird abgelehnt: Nur die ersten fünf Zeichen seines SHA-1-Hashes werden an Have I Been Pwned gesendet (k-Anonymität), nie das Passwort. Antwortet dieser Dienst nicht innerhalb von zwei Sekunden, wird das Passwort ohne die Prüfung akzeptiert.
Passwort vergessen? Die E-Mail zum Zurücksetzen verlinkt auf eine Seite, auf der Sie ein neues wählen. Der Link funktioniert einmal, läuft nach einer Stunde ab, und seine Verwendung meldet Sie auf allen Geräten ab.
Noch kein Passwort? Konten, die mit einem Code, einem Link, einem Passkey oder Google / Microsoft erstellt wurden, melden sich weiter auf diese Weise an und können unter Einstellungen › Konto ein Passwort hinzufügen. Das erste Passwort festzulegen erfordert eine Anmeldung innerhalb der letzten 15 Minuten (die Seite sendet Ihnen einen Code per E-Mail, um zu bestätigen, dass Sie es sind); zum Ändern ist das aktuelle Passwort nötig. Beides meldet Ihre anderen Sitzungen ab.
Fehler verraten nie Konten: Ein falsches Passwort, eine unbekannte Adresse und ein Konto ohne Passwort erhalten dieselbe Antwort, und eine Anfrage zum Zurücksetzen meldet immer, dass die E-Mail unterwegs ist.
Rate Limits: Anmeldung mit Passwort, Registrierung und Anfragen zum Zurücksetzen sind pro IP-Adresse und pro E-Mail-Adresse begrenzt; oberhalb des Limits lautet die Antwort 429, bis das Zeitfenster abgelaufen ist.
Unternehmens-SSO: Wenn Ihre Organisation SSO erzwingt, melden sich Mitglieder mit E-Mail-Adressen ihrer Domains nur über den Identitätsanbieter an. Passwörter, Codes und Magic Links werden für sie abgelehnt; Inhaber behalten den E-Mail-Code als Notfallzugang.

Anfrage-IDs

Jede Antwort enthält einen Header x-request-id, und jeder Fehler-Body eine requestId. Sie können eine eigene x-request-id (8 bis 128 Zeichen aus A-Z a-z 0-9 . _ -) senden, um Logs zu korrelieren; andernfalls erzeugt die API eine. Geben Sie sie an, wenn Sie den Support kontaktieren.