Autentisering

API:et autentiserar servrar med organisationens API-nycklar. En nyckel tillhör en organisation (inte en person), har en uppsättning behörigheter och fungerar i exakt ett läge: test eller live.

Skicka nyckeln

Använd någon av rubrikerna:

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

Nycklar ser ut som bf_live_… eller bf_test_…. En nyckel som saknas ger 401 (unauthorized); en felformaterad, återkallad eller utgången nyckel ger också 401. Behåll nycklarna på din server: skicka aldrig ut dem till en webbläsare eller en mobilapp. För signering i webbläsaren skapar du i stället en signeringssession.

Test- och livenycklar

	Test (`bf_test_…`)	Live (`bf_live_…`)
Dokument	Renderas med vattenmärket `TEST`	Utan vattenmärke
E-post	Levereras bara till medlemmar i din organisation	Levereras till alla mottagare
Debitering	Gratis och obegränsat, räknas aldrig	Slutförda kuvert räknas mot din plan
Data	Kuvert, länkar och webhook-slutpunkter som skapas med nyckeln är i testläge	Liveläge

Läget kommer från nyckeln, aldrig från begäran: ?test_mode=true på POST /v1/envelopes gäller bara sessioner i instrumentpanelen. Listor (GET /v1/envelopes, GET /v1/signing-links) returnerar bara nyckelns läge, och ett kuverts händelser går bara till webhook-slutpunkter i samma läge. Varje kuvert och varje webhook-nyttolast anger vilket läge det gäller (testMode).

Skapa och återkalla nycklar

Nycklar hanteras i instrumentpanelen, under Inställningar › API-nycklar, av medlemmar med behörigheten apikey:manage (ägare och administratörer). Hemligheten visas en gång, när nyckeln skapas. Du kan ge en nyckel ett namn, ett läge, ett utgångsdatum (1 till 365 dagar, eller inget) och behörighetsomfång.

Behörighetsomfång

En nyckels behörighetsomfång är de organisationsbehörigheter den får använda. Som standard får en ny nyckel skaparens behörigheter utom de administrativa (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), och ingen kan ge en nyckel en behörighet som hen inte själv har. Ett anrop utanför nyckelns omfång ger 403 med namnet på den behörighet som saknas:

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

Behörighet	Låter en nyckel
`template:read`	Lista och läsa mallar, versioner och deras PDF-filer
`template:write`	Skapa mallar, ladda upp filer, spara utkast, ta bort oanvända mallar
`template:publish`	Publicera ett utkast som en ny version
`envelope:read`	Lista och läsa kuvert, dokument och granskningsloggar; lista signeringslänkar
`envelope:send`	Skapa kuvert, signeringssessioner och signeringslänkar; skicka länkar igen
`envelope:void`	Makulera pågående kuvert
`org:manage`	Hantera webhook-slutpunkter och leverera händelser igen; läsa organisationens inställningar
`billing:manage`	Läsa användning (`GET /v1/usage`) och fakturabelopp

Att hantera webhook-slutpunkter kräver org:manage, som nycklar inte får som standard: registrera slutpunkter i instrumentpanelen, eller skapa uttryckligen en nyckel med det omfånget.

Vilka slutpunkter som tar vad

Varje åtgärd i API-referensen listar sina säkerhetsscheman. I korthet:

API-nyckel eller session i instrumentpanelen: mallar, kuvert, signeringssessioner, signeringslänkar, webhook-slutpunkter, organisationens inställningar, faktureringsöversikt och användning.
Endast session i instrumentpanelen: API-nycklar, SCIM-token, inställningar för SSO-anslutningar, uppladdning av organisationens logotyp, betalning och kundportal för fakturering, visning av en webhook-hemlighet.
Undertecknartoken: /v1/signing/*, som används av den hostade sidan och <bf-signing> med en sessionstoken (bfs_…) eller den åtkomsttoken den byts mot (bfa_…).
Offentligt: /v1/links/{id} (permanenta länkar), /v1/sso/discover och verifierings-API:et (/v1/public/*, /.well-known/bona-fide/keys.json).

Logga in i instrumentpanelen

Personer (inte servrar) loggar in i instrumentpanelen på https://app.bonafidesign.com/sign-in. Standard är e-post och lösenord; alternativen är en sexsiffrig kod via e-post (Mejla mig en kod i stället), en magisk länk, en passkey, Google eller Microsoft och ditt företags SSO.

Att skapa ett konto med lösenord skickar ett mejl: en kod som bekräftar att adressen är din. Fram till dess går det inte att logga in med lösenordet. Att registrera sig med en adress som redan har ett konto ändrar ingenting och ger exakt samma svar som en ny registrering; adressens ägare får ett mejl som förklarar hur man loggar in i stället.
Lösenord är 12 till 128 tecken långa och lagras som saltade scrypt-hashar. Ett nytt lösenord som förekommer i ett känt dataintrång nekas: bara de första fem tecknen i dess SHA-1-hash skickas till Have I Been Pwned (k-anonymitet), aldrig lösenordet. Om tjänsten inte svarar inom två sekunder godkänns lösenordet utan kontrollen.
Glömt lösenordet? Mejlet för återställning länkar till en sida där du väljer ett nytt. Länken fungerar en gång och går ut efter en timme, och när den används loggas du ut på alla enheter.
Inget lösenord än? Konton som skapats med en kod, en länk, en passkey eller Google / Microsoft fortsätter att logga in på det sättet och kan lägga till ett lösenord under Inställningar › Konto. Att ange det första lösenordet kräver en inloggning under de senaste 15 minuterna (sidan mejlar dig en kod för att bekräfta att det är du); att ändra det kräver det nuvarande. Båda loggar ut dina övriga sessioner.
Fel avslöjar aldrig konton: ett felaktigt lösenord, en okänd adress och ett konto utan lösenord får samma svar, och en begäran om återställning säger alltid att mejlet är på väg.
Hastighetsbegränsningar: inloggning med lösenord, registrering och begäran om återställning begränsas per IP-adress och per e-postadress; över gränsen blir svaret 429 tills tidsfönstret har passerat.
Företags-SSO: när din organisation kräver SSO loggar medlemmar med e-post i dess domäner bara in via identitetsleverantören. Lösenord, koder och magiska länkar nekas för dem; ägare behåller e-postkoden som nödinloggning.

Begärans id

Varje svar har en rubrik x-request-id, och varje felsvar en requestId. Du kan skicka ditt eget x-request-id (8 till 128 tecken av A-Z a-z 0-9 . _ -) för att korrelera loggar; annars genererar API:et ett. Ange det när du kontaktar supporten.