Vai al contenuto principale

Chiavi API

Le chiavi API (token di accesso personali) sono il modo più semplice per autenticarsi con l'API di B1 da uno script lato server, da un connettore di terze parti (Zapier, Make, Google Sheets) o in qualsiasi situazione in cui un flusso OAuth completo sarebbe eccessivo. Una chiave è legata a una persona specifica in una chiesa specifica ed eredita i permessi di quella persona, ristretti da un insieme facoltativo di ambiti (scope).

Prima di iniziare

  • Un amministratore della chiesa con il permesso Modifica impostazioni crea e gestisce le chiavi
  • La chiave completa viene mostrata una sola volta al momento della creazione -- conservala subito in un posto sicuro
  • Tutte le richieste API devono usare HTTPS

Formato della chiave​

Una chiave API di B1 ha questo aspetto:

cak_<prefix>.<secret>
  • cak_ -- identificatore fisso (il prefisso delle chiavi API che il livello di autenticazione riconosce)
  • <prefix> -- segmento pubblico di ricerca di 8 caratteri
  • <secret> -- segreto di 48 caratteri; sul server viene memorizzato solo un hash SHA-256

La chiave completa viene presentata al server nell'intestazione bearer standard:

Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7

Il livello di autenticazione dell'API instrada qualsiasi token che inizia con cak_ verso il percorso delle chiavi API, calcola l'hash del segreto, lo cerca tramite il prefisso e risolve i permessi attuali della persona associata alla chiave. Quindi revocare un permesso in B1Admin ha effetto già dalla richiesta successiva, e la chiave non si disallinea mai dal ruolo.

Creare una chiave (B1Admin)​

  1. Accedi a B1Admin con un utente che ha il permesso Modifica impostazioni.
  2. Apri Impostazioni → Sviluppatore → Chiavi API.
  3. Clicca su Nuova chiave API, assegnale un Nome riconoscibile (ad esempio "Zapier -- sincronizzazione donazioni"), seleziona almeno uno degli Ambiti che la chiave deve avere, facoltativamente scegli una data di Scadenza (lasciala vuota per una chiave che non scade mai), poi Salva.
  4. La chiave completa cak_… viene mostrata una sola volta in una finestra di dialogo. Copiala nella configurazione della tua integrazione prima di chiudere: non è possibile recuperarla in seguito. Puoi sempre crearne una nuova.

Ambiti​

Un ambito restringe ciò che una chiave può fare: non può mai concedere un permesso che la persona sottostante non ha. Nessun ambito significa che la chiave porta l'intero insieme di permessi della persona; B1Admin richiede sempre almeno un ambito, quindi una chiave senza ambiti può essere creata solo tramite l'API.

AmbitoConsente
people:read / people:writeVisualizzare / modificare persone, nuclei familiari, membri dei gruppi
groups:read / groups:writeVisualizzare / modificare gruppi e relative iscrizioni
donations:read / donations:writeVisualizzare / registrare donazioni
attendance:read / attendance:writeVisualizzare / registrare presenze, sessioni, check-in
forms:writeGestire i moduli (l'accesso in lettura è implicito nella scrittura)
content:read / content:writeVisualizzare / modificare contenuti del sito, iscrizioni, streaming
messaging:read / messaging:writeLeggere la messaggistica; la scrittura consente anche di inviare SMS
roles:read / roles:writeVisualizzare / modificare le definizioni dei ruoli
settings:read / settings:writeVisualizzare / modificare le impostazioni della chiesa (necessario per registrare webhook da programma)
workflows:read / workflows:writeVisualizzare flussi di lavoro e attività / eseguire e modificare flussi di lavoro. L'esecuzione di un flusso può inviare email e SMS, attivare webhook e modificare l'appartenenza ai gruppi
offline_accessConsente token di aggiornamento a lunga durata (solo flussi OAuth -- non ha effetto sulle chiavi API)

Gli ambiti write includono implicitamente il corrispondente read. I permessi di amministratore del server e del dominio non sono volutamente esposti come ambiti: una credenziale con ambiti limitati non potrà mai ottenere privilegi di amministrazione del sito.

Suggerimento

Se userai la chiave per registrare webhook (ad esempio per un'integrazione Zapier o Make), la chiave deve avere settings:write. Una chiave con solo people:read riceve silenziosamente un errore 403 su POST /membership/webhooks.

Usare una chiave​

Come per qualsiasi token bearer: ogni endpoint autenticato accetta le chiavi API esattamente come accetta i JWT:

curl https://api.churchapps.org/membership/people \
-H "Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7"

Una richiesta la cui chiave ha ambiti insufficienti risponde 403 Forbidden con la stessa struttura usata per qualsiasi errore di permesso negato.

Gestire le chiavi tramite l'API​

Tutti gli endpoint si trovano sotto il percorso /membership/apiKeys del modulo Membership e richiedono un JWT (non una chiave API) di un amministratore della chiesa con Modifica impostazioni.

Metodo e percorsoScopo
GET /membership/apiKeysElenca le chiavi della chiesa (senza segreto -- solo id, name, prefix, scopes, lastUsedAt, expiresAt, createdAt)
GET /membership/apiKeys/scopesElenco di tutti i nomi di ambito disponibili -- per un'interfaccia di creazione delle chiavi
POST /membership/apiKeysCrea una nuova chiave. Corpo: { "name": "...", "scopes": ["people:read"] }. La risposta include la chiave cak_… completa una sola volta.
DELETE /membership/apiKeys/:idRevoca una chiave -- ha effetto dalla richiesta successiva

Una chiave revocata smette di funzionare immediatamente: non c'è alcun periodo di tolleranza.

Buone pratiche​

  • Una chiave per integrazione. Se una chiave viene compromessa, la revochi senza interrompere le altre.
  • Crea gli ambiti più ristretti possibili. Un export su Google Sheets ha bisogno solo di people:read, non di settings:write.
  • Associa la chiave a un account di servizio, non a un membro dello staff reale. Se un membro dello staff lascia la chiesa, il suo accesso a B1 termina -- e con esso anche le chiavi create con la sua identità.
  • Conserva le chiavi in un gestore di segreti (le variabili d'ambiente del tuo provider di hosting, AWS Secrets Manager e simili) -- mai nel controllo di versione.
  • Ruota le chiavi se sospetti una esposizione: crea una nuova chiave, aggiorna l'integrazione, poi elimina quella vecchia.

Differenze rispetto a OAuth​

Le chiavi API sono adatte quando la tua chiesa è l'unica a usare l'integrazione. Per un connettore che deve accedere a molte chiese, ciascuna con il proprio consenso esplicito -- come un'app SaaS condivisa nella comunità B1 -- usa invece OAuth e App connesse.

Chiave APIOAuth
Chi la installaUn amministratore di una sola chiesaOgni amministratore della chiesa autorizza l'app
Intestazione di autenticazioneAuthorization: Bearer cak_…Authorization: Bearer <jwt>
Durata del tokenFino alla revocaAccesso ≈ 7 giorni, aggiornamento ≈ 90 giorni
Ideale perScript interni, connettori Zapier/Make/SheetsApp di terze parti multi-tenant