Autentisering

API-et autentiserer servere med API-nøkler for organisasjonen. En nøkkel tilhører en organisasjon (ikke en person), har et sett med tillatelser og fungerer i nøyaktig én modus: test eller produksjon (live).

Sende nøkkelen

Bruk en av disse headerne:

# 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økler ser ut som bf_live_… eller bf_test_…. En manglende nøkkel gir 401 (unauthorized); en ugyldig formatert, tilbakekalt eller utløpt nøkkel gir også 401. Hold nøklene på serveren: send dem aldri til en nettleser eller en mobilapp. For signering i nettleseren oppretter du i stedet en signeringsøkt.

Test- og produksjonsnøkler

	Test (`bf_test_…`)	Produksjon (`bf_live_…`)
Dokumenter	Rendres med vannmerket `TEST`	Uten vannmerke
E-post	Leveres bare til medlemmer av organisasjonen din	Leveres til alle mottakere
Fakturering	Gratis og ubegrenset, telles aldri	Fullførte konvolutter teller mot planen din
Data	Konvolutter, lenker og webhook-endepunkter som opprettes med nøkkelen, er i testmodus	I produksjonsmodus

Modusen kommer fra nøkkelen, aldri fra forespørselen: ?test_mode=true på POST /v1/envelopes gjelder bare for dashbordøkter. Lister (GET /v1/envelopes, GET /v1/signing-links) returnerer bare nøkkelens modus, og hendelsene til en konvolutt går bare til webhook-endepunkter i samme modus. Hver konvolutt og hver webhook-nyttelast oppgir hvilken modus den er i (testMode).

Opprette og tilbakekalle nøkler

Nøkler administreres i dashbordet, under Innstillinger › API-nøkler, av medlemmer med tillatelsen apikey:manage (eiere og administratorer). Hemmeligheten vises én gang, når nøkkelen opprettes. Du kan gi en nøkkel et navn, en modus, en utløpstid (1 til 365 dager, eller ingen) og tilgangsomfang.

Tilgangsomfang

Tilgangsomfanget til en nøkkel er de tillatelsene i organisasjonen den kan bruke. Som standard får en ny nøkkel tillatelsene til den som opprettet den, unntatt de administrative (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), og ingen kan gi en nøkkel en tillatelse de ikke har selv. Et kall utenfor nøkkelens omfang gir 403 med navnet på den manglende tillatelsen:

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

Tillatelse	Lar en nøkkel
`template:read`	Liste opp og lese maler, versjoner og PDF-ene deres
`template:write`	Opprette maler, laste opp filer, lagre utkast, slette ubrukte maler
`template:publish`	Publisere et utkast som en ny versjon
`envelope:read`	Liste opp og lese konvolutter, dokumenter og revisjonsspor; liste opp signeringslenker
`envelope:send`	Opprette konvolutter, signeringsøkter og signeringslenker; sende lenker på nytt
`envelope:void`	Annullere konvolutter som er underveis
`org:manage`	Administrere webhook-endepunkter og levere hendelser på nytt; lese organisasjonsinnstillinger
`billing:manage`	Lese forbruk (`GET /v1/usage`) og fakturabeløp

Å administrere webhook-endepunkter krever org:manage, som nøkler ikke får som standard: registrer endepunkter i dashbordet, eller opprett en nøkkel med det omfanget eksplisitt.

Hvilke endepunkter som godtar hva

Hver operasjon i API-referansen viser sine sikkerhetsskjemaer. Kort fortalt:

API-nøkkel eller dashbordøkt: maler, konvolutter, signeringsøkter, signeringslenker, webhook-endepunkter, organisasjonsinnstillinger, faktureringsoversikt og forbruk.
Bare dashbordøkt: API-nøkler, SCIM-tokener, innstillinger for SSO-tilkoblinger, opplasting av organisasjonslogo, betaling og kundeportal for fakturering, visning av en webhook-hemmelighet.
Signatartoken: /v1/signing/*, som brukes av den hostede siden og <bf-signing> med et økttoken (bfs_…) eller tilgangstokenet det byttes mot (bfa_…).
Offentlig: /v1/links/{id} (faste lenker), /v1/sso/discover og verifiserings-API-et (/v1/public/*, /.well-known/bona-fide/keys.json).

Logge inn i dashbordet

Personer (ikke servere) logger inn i dashbordet på https://app.bonafidesign.com/sign-in. Standard er e-post og passord; alternativene er en sekssifret kode på e-post (Send meg en kode i stedet), en magisk lenke, en passnøkkel, Google eller Microsoft og bedriftens SSO.

Når du oppretter en konto med passord, sendes én e-post: en kode som bekrefter at adressen er din. Før det kan du ikke logge inn med passordet. Registrering med en adresse som allerede har en konto, endrer ingenting og får nøyaktig samme svar som en ny registrering; eieren av adressen får en e-post som forklarer hvordan de logger inn i stedet.
Passord er 12 til 128 tegn og lagres som saltede scrypt-hasher. Et nytt passord som finnes i et kjent datainnbrudd, avvises: bare de fem første tegnene i SHA-1-hashen sendes til Have I Been Pwned (k-anonymitet), aldri selve passordet. Hvis tjenesten ikke svarer innen to sekunder, godtas passordet uten kontrollen.
Glemt passordet? E-posten for tilbakestilling lenker til en side der du velger et nytt. Lenken fungerer én gang og utløper etter én time, og når du bruker den, logges du ut på alle enheter.
Ikke noe passord ennå? Kontoer som er opprettet med en kode, en lenke, en passnøkkel eller Google / Microsoft, fortsetter å logge inn på den måten og kan legge til et passord under Innstillinger › Konto. For å angi det første passordet må du ha logget inn i løpet av de siste 15 minuttene (siden sender deg en kode på e-post for å bekrefte at det er deg); for å endre det trenger du det nåværende. Begge deler logger ut de andre øktene dine.
Feil avslører aldri kontoer: et feil passord, en ukjent adresse og en konto uten passord får samme svar, og en forespørsel om tilbakestilling sier alltid at e-posten er på vei.
Hastighetsgrenser: innlogging med passord, registrering og forespørsler om tilbakestilling er begrenset per IP-adresse og per e-postadresse; over grensen er svaret 429 til tidsvinduet er over.
Bedrifts-SSO: når organisasjonen din håndhever SSO, logger medlemmer med e-post på organisasjonens domener inn bare via identitetsleverandøren. Passord, koder og magiske lenker avvises for dem; eiere beholder e-postkoden som nødinnlogging.

Forespørsels-ID-er

Hvert svar har en x-request-id-header, og hver feilmelding har en requestId. Du kan sende din egen x-request-id (8 til 128 tegn av A-Z a-z 0-9 . _ -) for å koble sammen logger; ellers genererer API-et en. Oppgi den når du kontakter kundestøtte.