Autenticazione

L’API autentica i server con chiavi API dell’organizzazione. Una chiave appartiene a un’organizzazione (non a una persona), dispone di un insieme di autorizzazioni e funziona in una sola modalità: prova o produzione.

Invio della chiave

Usi uno dei due 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_…"

Le chiavi hanno la forma bf_live_… o bf_test_…. Una chiave mancante produce un 401 (unauthorized); anche una chiave malformata, revocata o scaduta produce un 401. Tenga le chiavi sul Suo server: non le distribuisca mai in un browser o in un’app mobile. Per firmare nel browser, crei invece una sessione di firma.

Chiavi di prova e di produzione

	Prova (`bf_test_…`)	Produzione (`bf_live_…`)
Documenti	Composti con la filigrana `TEST`	Senza filigrana
E-mail	Recapitate solo ai membri della Sua organizzazione	Recapitate a ogni destinatario
Fatturazione	Gratuita e illimitata, mai conteggiata	Le buste completate vengono conteggiate nel Suo piano
Dati	Buste, link ed endpoint webhook creati con la chiave sono in modalità di prova	In modalità di produzione

La modalità dipende dalla chiave, mai dalla richiesta: ?test_mode=true su POST /v1/envelopes vale solo per le sessioni della dashboard. Gli elenchi (GET /v1/envelopes, GET /v1/signing-links) restituiscono solo la modalità della chiave e gli eventi di una busta vengono inviati solo agli endpoint webhook della stessa modalità. Ogni busta e ogni payload webhook indica la propria modalità (testMode).

Creazione e revoca delle chiavi

Le chiavi si gestiscono nella dashboard, in Impostazioni › Chiavi API, da parte dei membri con l’autorizzazione apikey:manage (proprietari e amministratori). Il segreto viene mostrato una sola volta, alla creazione della chiave. A una chiave si possono assegnare un nome, una modalità, una scadenza (da 1 a 365 giorni, o nessuna) e degli ambiti.

Ambiti

Gli ambiti di una chiave sono le autorizzazioni dell’organizzazione che può usare. Per impostazione predefinita una nuova chiave riceve le autorizzazioni di chi la crea, escluse quelle amministrative (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), e nessuno può concedere a una chiave un’autorizzazione che non possiede. Una chiamata al di fuori degli ambiti della chiave produce un 403 che indica l’autorizzazione mancante:

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

Autorizzazione	Consente a una chiave di
`template:read`	Elencare e leggere modelli, versioni e i relativi PDF
`template:write`	Creare modelli, caricare file, salvare bozze, eliminare modelli non utilizzati
`template:publish`	Pubblicare una bozza come nuova versione
`envelope:read`	Elencare e leggere buste, documenti e audit trail; elencare i link di firma
`envelope:send`	Creare buste, sessioni di firma e link di firma; inviare di nuovo i link
`envelope:void`	Annullare buste in corso
`org:manage`	Gestire gli endpoint webhook e riconsegnare eventi; leggere le impostazioni dell’organizzazione
`billing:manage`	Leggere l’utilizzo (`GET /v1/usage`) e gli importi delle fatture

La gestione degli endpoint webhook richiede org:manage, che le chiavi non ricevono per impostazione predefinita: registri gli endpoint nella dashboard oppure crei esplicitamente una chiave con quell’ambito.

Che cosa accetta ciascun endpoint

Ogni operazione nel riferimento API elenca i propri schemi di sicurezza. In sintesi:

Chiave API o sessione della dashboard: modelli, buste, sessioni di firma, link di firma, endpoint webhook, impostazioni dell’organizzazione, panoramica di fatturazione e utilizzo.
Solo sessione della dashboard: chiavi API, token SCIM, impostazioni della connessione SSO, caricamento del logo dell’organizzazione, checkout e portale di fatturazione, visualizzazione di un segreto webhook.
Token del firmatario: /v1/signing/*, usato dalla pagina ospitata e da <bf-signing> con un token di sessione (bfs_…) o con il token di accesso con cui viene scambiato (bfa_…).
Pubblico: /v1/links/{id} (link sempre attivi), /v1/sso/discover e l’API di verifica (/v1/public/*, /.well-known/bona-fide/keys.json).

Accesso alla dashboard

Le persone (non i server) accedono alla dashboard all’indirizzo https://app.bonafidesign.com/sign-in. Il metodo predefinito è e-mail e password; le alternative sono un codice di sei cifre inviato via e-mail (Inviami invece un codice via e-mail), un magic link, una passkey, Google o Microsoft e l’SSO della Sua azienda.

La creazione di un account con password invia una sola e-mail: un codice che conferma che l’indirizzo è Suo. Fino ad allora la password non consente l’accesso. Registrarsi con un indirizzo che ha già un account non cambia nulla e produce esattamente la stessa risposta di una nuova registrazione; il titolare dell’indirizzo riceve invece un’e-mail che spiega come accedere.
Le password hanno da 12 a 128 caratteri e sono memorizzate come hash scrypt con salt. Una nuova password che compare in una violazione di dati nota viene rifiutata: a Have I Been Pwned vengono inviati solo i primi cinque caratteri del suo hash SHA-1 (k-anonimato), mai la password. Se il servizio non risponde entro due secondi, la password viene accettata senza il controllo.
Password dimenticata? L’e-mail di reimpostazione rimanda a una pagina in cui sceglierne una nuova. Il link funziona una sola volta, scade dopo un’ora e, se usato, La disconnette da tutti i dispositivi.
Non ha ancora una password? Gli account creati con un codice, un link, una passkey o Google / Microsoft continuano ad accedere in quel modo e possono aggiungere una password in Impostazioni › Account. Per impostare la prima password serve un accesso negli ultimi 15 minuti (la pagina Le invia via e-mail un codice per confermare che è Lei); per cambiarla serve quella attuale. In entrambi i casi le altre sessioni vengono disconnesse.
Gli errori non rivelano mai gli account: una password errata, un indirizzo sconosciuto e un account senza password ricevono la stessa risposta, e una richiesta di reimpostazione risponde sempre che l’e-mail è in arrivo.
Limiti di frequenza: le richieste di accesso con password, di registrazione e di reimpostazione sono limitate per indirizzo IP e per indirizzo e-mail; oltre il limite la risposta è 429 finché la finestra non è trascorsa.
SSO aziendale: quando la Sua organizzazione impone l’SSO, i membri dei suoi domini e-mail accedono solo tramite l’identity provider. Password, codici e magic link vengono rifiutati per loro; i proprietari mantengono il codice via e-mail come accesso di emergenza.

ID delle richieste

Ogni risposta contiene un header x-request-id e ogni corpo di errore un requestId. Può inviare un Suo x-request-id (da 8 a 128 caratteri tra A-Z a-z 0-9 . _ -) per correlare i log; altrimenti l’API ne genera uno. Lo indichi quando contatta l’assistenza.