Authenticatie

De API authenticeert servers met API-keys van de organisatie. Een key hoort bij een organisatie (niet bij een persoon), heeft een set rechten en werkt in precies één modus: test of live.

De key meesturen

Gebruik een van beide headers:

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

Keys zien eruit als bf_live_… of bf_test_…. Een ontbrekende key geeft een 401 (unauthorized); een ongeldig opgemaakte, ingetrokken of verlopen key geeft ook een 401. Houd keys op uw server: lever ze nooit uit naar een browser of een mobiele app. Maak voor ondertekening in de browser in plaats daarvan een ondertekeningssessie aan.

Test- en live keys

	Test (`bf_test_…`)	Live (`bf_live_…`)
Documenten	Gerenderd met een `TEST`-watermerk	Zonder watermerk
E-mail	Alleen bezorgd bij leden van uw organisatie	Bezorgd bij elke ontvanger
Facturering	Gratis en onbeperkt, telt nooit mee	Voltooide enveloppen tellen mee voor uw abonnement
Data	Enveloppen, links en webhook-endpoints die met de key zijn gemaakt, staan in testmodus	Livemodus

De modus komt van de key, nooit van het request: ?test_mode=true op POST /v1/envelopes geldt alleen voor dashboardsessies. Lijsten (GET /v1/envelopes, GET /v1/signing-links) geven alleen de modus van de key terug, en de events van een envelop gaan alleen naar webhook-endpoints in dezelfde modus. Elke envelop en elke webhook-payload vermeldt in welke modus die staat (testMode).

Keys aanmaken en intrekken

Keys worden beheerd in het dashboard, onder Instellingen › API-keys, door leden met het recht apikey:manage (eigenaren en beheerders). Het geheim wordt één keer getoond, bij het aanmaken van de key. U kunt een key een naam, een modus, een vervaldatum (1 tot 365 dagen, of geen) en scopes geven.

Scopes

De scopes van een key zijn de rechten binnen de organisatie die de key mag gebruiken. Standaard krijgt een nieuwe key de rechten van de maker, zonder de beheerrechten (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), en niemand kan een key een recht geven dat hij of zij zelf niet heeft. Een call buiten de scopes van de key geeft een 403 die het ontbrekende recht noemt:

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

Recht	Hiermee kan een key
`template:read`	Sjablonen, versies en hun pdf’s opvragen en lezen
`template:write`	Sjablonen aanmaken, bestanden uploaden, concepten opslaan, ongebruikte sjablonen verwijderen
`template:publish`	Een concept publiceren als nieuwe versie
`envelope:read`	Enveloppen, documenten en audittrails opvragen en lezen; ondertekeningslinks opvragen
`envelope:send`	Enveloppen, ondertekeningssessies en ondertekeningslinks aanmaken; links opnieuw versturen
`envelope:void`	Lopende enveloppen intrekken
`org:manage`	Webhook-endpoints beheren en events opnieuw bezorgen; organisatie-instellingen lezen
`billing:manage`	Verbruik (`GET /v1/usage`) en factuurbedragen lezen

Voor het beheren van webhook-endpoints is org:manage nodig, dat keys standaard niet krijgen: registreer endpoints in het dashboard, of maak expliciet een key met die scope aan.

Welke endpoints wat accepteren

Elke operatie in de API-naslag vermeldt haar beveiligingsschema’s. In het kort:

API-key of dashboardsessie: sjablonen, enveloppen, ondertekeningssessies, ondertekeningslinks, webhook-endpoints, organisatie-instellingen, factureringsoverzicht en verbruik.
Alleen dashboardsessie: API-keys, SCIM-tokens, instellingen van de SSO-verbinding, uploaden van het organisatielogo, checkout en portaal voor facturering, een webhookgeheim tonen.
Ondertekenaarstoken: /v1/signing/*, gebruikt door de gehoste pagina en <bf-signing> met een sessietoken (bfs_…) of het toegangstoken waarvoor het wordt ingewisseld (bfa_…).
Openbaar: /v1/links/{id} (permanente links), /v1/sso/discover en de verificatie-API (/v1/public/*, /.well-known/bona-fide/keys.json).

Inloggen op het dashboard

Mensen (geen servers) loggen in op het dashboard via https://app.bonafidesign.com/sign-in. Standaard is dat met e-mailadres en wachtwoord; de alternatieven zijn een zescijferige code per e-mail (Stuur me in plaats daarvan een code), een magic link, een passkey, Google of Microsoft, en de SSO van uw bedrijf.

Een account aanmaken met een wachtwoord verstuurt één e-mail: een code die bevestigt dat het adres van u is. Tot dan kunt u niet inloggen met het wachtwoord. Registreren met een adres dat al een account heeft, verandert niets en geeft precies hetzelfde antwoord als een nieuwe registratie; de eigenaar van het adres krijgt in plaats daarvan een e-mail met uitleg over hoe die kan inloggen.
Wachtwoorden zijn 12 tot 128 tekens lang en worden opgeslagen als gesalte scrypt-hashes. Een nieuw wachtwoord dat voorkomt in een bekend datalek wordt geweigerd: alleen de eerste vijf tekens van de SHA-1-hash ervan worden naar Have I Been Pwned gestuurd (k-anonimiteit), nooit het wachtwoord zelf. Als die dienst niet binnen twee seconden antwoordt, wordt het wachtwoord zonder controle geaccepteerd.
Wachtwoord vergeten? De resetmail linkt naar een pagina waar u een nieuw wachtwoord kiest. De link werkt één keer, verloopt na een uur en als u hem gebruikt, wordt u op elk apparaat uitgelogd.
Nog geen wachtwoord? Accounts die zijn aangemaakt met een code, een link, een passkey of Google / Microsoft blijven op die manier inloggen en kunnen een wachtwoord toevoegen in Instellingen › Account. Voor het instellen van het eerste wachtwoord is een login in de afgelopen 15 minuten nodig (de pagina mailt u een code om te bevestigen dat u het bent); voor het wijzigen is het huidige wachtwoord nodig. In beide gevallen worden uw andere sessies uitgelogd.
Fouten verraden nooit accounts: een verkeerd wachtwoord, een onbekend adres en een account zonder wachtwoord krijgen hetzelfde antwoord, en een resetverzoek meldt altijd dat de e-mail onderweg is.
Rate limits: inloggen met een wachtwoord, registreren en resetverzoeken zijn beperkt per IP-adres en per e-mailadres; boven de limiet is het antwoord 429 totdat het tijdvenster voorbij is.
SSO van het bedrijf: wanneer uw organisatie SSO afdwingt, loggen leden met een e-mailadres op de domeinen van de organisatie alleen in via de identityprovider. Wachtwoorden, codes en magic links worden voor hen geweigerd; eigenaren houden de e-mailcode als noodtoegang.

Request-id’s

Elk antwoord bevat een x-request-id-header en elke foutbody een requestId. U kunt zelf een x-request-id meesturen (8 tot 128 tekens uit A-Z a-z 0-9 . _ -) om logs aan elkaar te koppelen; anders genereert de API er een. Vermeld het id wanneer u contact opneemt met support.