Godkendelse

API’et godkender servere med organisationens API-nøgler. En nøgle tilhører en organisation (ikke en person), har et sæt tilladelser og fungerer i præcis én tilstand: test eller live.

Afsendelse af nøglen

Brug en af disse 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_…"

Nøgler ser ud som bf_live_… eller bf_test_…. En manglende nøgle giver 401 (unauthorized); en ugyldigt formateret, tilbagekaldt eller udløbet nøgle giver også 401. Hold nøglerne på din server: send dem aldrig ud til en browser eller en mobilapp. Til underskrift i browseren opretter du i stedet en signeringssession.

Test- og live-nøgler

	Test (`bf_test_…`)	Live (`bf_live_…`)
Dokumenter	Renderes med vandmærket `TEST`	Uden vandmærke
E-mail	Leveres kun til medlemmer af din organisation	Leveres til alle modtagere
Fakturering	Gratis og ubegrænset, tælles aldrig med	Fuldførte kuverter tæller med i din plan
Data	Kuverter, links og webhook-slutpunkter, der oprettes med nøglen, er i testtilstand	Live-tilstand

Tilstanden kommer fra nøglen, aldrig fra anmodningen: ?test_mode=true på POST /v1/envelopes gælder kun for dashboardsessioner. Lister (GET /v1/envelopes, GET /v1/signing-links) returnerer kun nøglens tilstand, og en kuverts hændelser går kun til webhook-slutpunkter i samme tilstand. Hver kuvert og hver webhook-payload angiver, hvilken tilstand den er i (testMode).

Oprettelse og tilbagekaldelse af nøgler

Nøgler administreres i dashboardet under Indstillinger › API-nøgler af medlemmer med tilladelsen apikey:manage (ejere og administratorer). Hemmeligheden vises én gang, når nøglen oprettes. Du kan give en nøgle et navn, en tilstand, en udløbsdato (1 til 365 dage eller ingen) og tilladelsesomfang.

Tilladelsesomfang

En nøgles tilladelsesomfang er de organisationstilladelser, den må bruge. Som standard får en ny nøgle opretterens tilladelser undtagen de administrative (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), og ingen kan give en nøgle en tilladelse, de ikke selv har. Et kald uden for nøglens omfang giver 403 med navnet på den manglende tilladelse:

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

Tilladelse	Giver en nøgle lov til at
`template:read`	Vise og læse skabeloner, versioner og deres PDF’er
`template:write`	Oprette skabeloner, uploade filer, gemme kladder, slette ubrugte skabeloner
`template:publish`	Udgive en kladde som en ny version
`envelope:read`	Vise og læse kuverter, dokumenter og revisionsspor; vise underskriftslinks
`envelope:send`	Oprette kuverter, signeringssessioner og underskriftslinks; gensende links
`envelope:void`	Annullere igangværende kuverter
`org:manage`	Administrere webhook-slutpunkter og levere hændelser igen; læse organisationens indstillinger
`billing:manage`	Læse forbrug (`GET /v1/usage`) og fakturabeløb

Administration af webhook-slutpunkter kræver org:manage, som nøgler ikke får som standard: registrer slutpunkter i dashboardet, eller opret udtrykkeligt en nøgle med det omfang.

Hvilke slutpunkter der accepterer hvad

Hver handling i API-referencen angiver sine sikkerhedsskemaer. Kort sagt:

API-nøgle eller dashboardsession: skabeloner, kuverter, signeringssessioner, underskriftslinks, webhook-slutpunkter, organisationens indstillinger, faktureringsoversigt og forbrug.
Kun dashboardsession: API-nøgler, SCIM-tokens, indstillinger for SSO-forbindelser, upload af organisationens logo, betaling og kundeportal for fakturering, visning af en webhook-hemmelighed.
Underskrivertoken: /v1/signing/*, som bruges af den hostede side og <bf-signing> med et sessionstoken (bfs_…) eller det adgangstoken, det byttes til (bfa_…).
Offentligt: /v1/links/{id} (permanente links), /v1/sso/discover og verificerings-API’et (/v1/public/*, /.well-known/bona-fide/keys.json).

Personer (ikke servere) logger ind i dashboardet på https://app.bonafidesign.com/sign-in. Standard er e-mail og adgangskode; alternativerne er en sekscifret kode pr. e-mail (Send mig en kode i stedet), et magisk link, en adgangsnøgle (passkey), Google eller Microsoft og din virksomheds SSO.

Når du opretter en konto med adgangskode, sendes der én e-mail: en kode, der bekræfter, at adressen er din. Indtil da kan du ikke logge ind med adgangskoden. Tilmelding med en adresse, der allerede har en konto, ændrer intet og giver præcis samme svar som en ny tilmelding; adressens ejer får en e-mail, der i stedet forklarer, hvordan man logger ind.
Adgangskoder er på 12 til 128 tegn og gemmes som saltede scrypt-hashes. En ny adgangskode, der optræder i et kendt datalæk, afvises: kun de første fem tegn af dens SHA-1-hash sendes til Have I Been Pwned (k-anonymitet), aldrig selve adgangskoden. Hvis tjenesten ikke svarer inden for to sekunder, accepteres adgangskoden uden tjekket.
Glemt din adgangskode? E-mailen til nulstilling linker til en side, hvor du vælger en ny. Linket virker én gang og udløber efter en time, og når det bruges, logges du ud på alle enheder.
Ingen adgangskode endnu? Konti, der er oprettet med en kode, et link, en adgangsnøgle eller Google / Microsoft, logger fortsat ind på den måde og kan tilføje en adgangskode under Indstillinger › Konto. Den første adgangskode kræver et login inden for de seneste 15 minutter (siden sender dig en kode pr. e-mail for at bekræfte, at det er dig); en ændring kræver den nuværende. Begge dele logger dine andre sessioner ud.
Fejl afslører aldrig konti: en forkert adgangskode, en ukendt adresse og en konto uden adgangskode får samme svar, og en anmodning om nulstilling siger altid, at e-mailen er på vej.
Hastighedsbegrænsning: login med adgangskode, tilmelding og anmodninger om nulstilling begrænses pr. IP-adresse og pr. e-mailadresse; over grænsen er svaret 429, indtil tidsvinduet er gået.
Virksomheds-SSO: når din organisation håndhæver SSO, logger medlemmer med e-mail i dens domæner kun ind via identitetsudbyderen. Adgangskoder, koder og magiske links afvises for dem; ejere beholder e-mailkoden som nødlogin.

Anmodnings-id’er

Hvert svar har en x-request-id-header, og hver fejlmeddelelse et requestId. Du kan sende dit eget x-request-id (8 til 128 tegn af A-Z a-z 0-9 . _ -) for at korrelere logs; ellers genererer API’et et. Oplys det, når du kontakter support.