Chiavi API e ambiti

Ogni richiesta all’API di Sursa viene fatta con una chiave API della tua organizzazione. Una chiave appartiene all’organizzazione, non a una persona: continua a funzionare quando il dipendente che l’ha creata se ne va, e ciò che può fare è impostato sulla chiave stessa.

Cosa può fare una chiave

Tre impostazioni di una chiave decidono cosa può vedere e modificare una richiesta fatta con essa. Ognuna restringe soltanto le altre.

Una chiave può anche essere limitata ad alcune raccolte e ricevere una data di scadenza. Una richiesta fuori da questi limiti non riesce: un ambito mancante restituisce 403 con il codice api_keys.scope, e un oggetto che la chiave non può vedere restituisce 404, esattamente come se non esistesse.

Dai a ogni integrazione una chiave propria, con il ruolo e gli ambiti più ristretti che le servono. Un job di sincronizzazione che scrive soltanto documenti non ha bisogno di admin; un job di reportistica non ha bisogno di ambiti di scrittura.

Creare una chiave

Un amministratore dell’organizzazione crea le chiavi in Sursa in Administration → API keys (amministrazione, chiavi API), oppure con POST /v1/api-keys usando una chiave o una sessione con il ruolo admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

La risposta contiene il valore della chiave in key. Viene mostrato una sola volta: Sursa ne conserva solo un hash e non può mostrarlo di nuovo. Una chiave ha la forma kb_ seguito da 43 caratteri; i primi caratteri (prefix) compaiono nell’elenco delle chiavi, così puoi distinguerle.

Senza scopes, la chiave riceve gli ambiti del suo ruolo. Passa scopes per restringerla ulteriormente. Senza expires_at, la chiave non scade.

Mantenere segrete le chiavi

• Conserva le chiavi in un gestore dei segreti o nelle variabili d’ambiente del tuo servizio, mai nel codice sorgente.
• Usa le chiavi solo dai tuoi server. Sursa accetta richieste dai browser (CORS è aperto), ma una chiave in una pagina web è visibile a chiunque la apra.
• Non inviare mai una chiave in un URL. Inviala solo nell’intestazione Authorization.
• Se una chiave viene divulgata, revocala subito e creane una nuova.

Verificare una chiave

GET /v1/me restituisce la chiave, il suo ruolo, gli ambiti effettivi, il profilo dati, la scadenza e il limite di frequenza. Funziona con qualsiasi chiave valida, qualunque siano i suoi ambiti: usala come test di connessione della tua integrazione e quando indaghi su un 403.

Ruotare una chiave

La rotazione sostituisce una chiave senza fermare l’integrazione. Il modo più rapido è ruotare la chiave stessa: POST /v1/api-keys/{key_id}/roll emette un nuovo valore per la stessa chiave, con lo stesso ruolo, gli stessi ambiti, le stesse raccolte e la stessa scadenza. Il valore precedente continua a funzionare per overlap_hours (24 ore per impostazione predefinita, fino a 168), così nel frattempo puoi distribuire il nuovo valore; POST /v1/api-keys/{key_id}/revoke-previous termina prima la sovrapposizione.

Per sostituire invece una chiave con un’altra:

1. Crea una nuova chiave con lo stesso ruolo, gli stessi ambiti e lo stesso profilo dati.
2. Distribuisci la nuova chiave alla tua integrazione.
3. Osserva la vecchia chiave in Administration → API keys (o last_used in GET /v1/api-keys) finché non viene più usata.
4. Revoca la vecchia chiave.

Imposta una data di scadenza sulle chiavi e ruotale prima di quella data. Sursa avvisa gli amministratori dell’organizzazione prima che una chiave scada; una chiave scaduta restituisce 401 con il codice api_keys.expired.

Revocare una chiave

Revoca una chiave in Administration → API keys oppure con DELETE /v1/api-keys/{key_id}. La revoca ha effetto entro pochi secondi su tutti i server dell’API. Le richieste con una chiave revocata restituiscono 401 con il codice auth.not_authenticated.

Chiavi di una fonte personalizzata

Una fonte personalizzata ha un tipo di chiave tutto suo. Inizia con kbsrc_, può solo scrivere documenti in quella fonte e non può leggere né cercare nulla. È la chiave più sicura da dare a una piattaforma di integrazione come Zapier. Creala nella pagina della fonte, in API keys (chiavi API della fonte), oppure con POST /v1/sources/{source_id}/push-keys.

Quando le chiavi non sono disponibili

Le chiavi API fanno parte del piano dell’organizzazione. Se il piano non le include, la creazione di una chiave e ogni richiesta con una chiave restituiscono 403 con il codice api_keys.feature_disabled.