API e chiavi di integrazione
Le chiavi API permettono ai tuoi sistemi di parlare con CRAnotify — oggi soprattutto per inviare le distinte base dalle pipeline. Si gestiscono da Area utente › API ed è un’operazione da amministratore.
Creare una chiave
- Indica un nome che dica a che cosa serve («CI build backend», «Dependency-Track produzione»), non «chiave 1».
- Seleziona i permessi: solo quelli necessari.
- Alla creazione il segreto completo compare una volta sola. Copialo subito nel gestore dei segreti del tuo sistema.
Il segreto non è recuperabile: il sistema ne conserva solo l’impronta. Se lo perdi, ruota la chiave — è un’operazione di pochi secondi, e nessuno dovrebbe conservare un segreto in chiaro «per sicurezza».
Permessi
| Permesso | Consente |
|---|---|
incidents:write | Registrare un segnale di sicurezza in ingresso. |
products:read | Leggere il catalogo prodotti con stato SBOM e livello di rischio. |
compliance:read | Leggere il punteggio di conformità dell’organizzazione. |
products:write | Inviare le distinte base dalle pipeline. |
Seleziona solo i permessi necessari: non esistono chiavi «tuttofare». Una chiave usata per un’operazione fuori dai suoi permessi riceve un rifiuto esplicito con 403. L’elenco completo degli endpoint che ciascun permesso sblocca è nel Riferimento API v1.
Autenticare una chiamata
X-CRA-API-Key: cra_live_…
# in alternativa
Authorization: Bearer cra_live_…Esempio completo di invio SBOM per uno SKU (vedi Distinta base e strumenti SBOM):
curl -X POST https://api.cranotify.eu/api/v1/external/products/SKU-123/sbom \
-H "X-CRA-API-Key: cra_live_…" \
-H "Content-Type: application/json" \
--data-binary @sbom.json| Codice | Significato |
|---|---|
401 | Chiave assente, errata, revocata o scaduta. |
403 | La chiave è valida ma priva del permesso richiesto. |
422 | Contenuto non riconosciuto (formato SBOM non valido). |
405 | Metodo non consentito: l’ingestione accetta solo POST. |
429 | Limite di frequenza superato (100/min per chiave). |
Rotazione e revoca
Creazione, rotazione e revoca lasciano una riga nel registro delle attività, con il nome della chiave (mai il segreto).
Buona pratica. Una chiave per sistema, mai una condivisa fra più integrazioni: solo così la revoca colpisce ciò che deve e nient’altro. Ruota a ogni cambio di personale che aveva accesso ai segreti.
L’host API pubblico
L’API pubblica risponde su api.<dominio>. Espone quattro endpoint: apertura di un segnale in ingresso, lettura del catalogo prodotti, lettura del punteggio di conformità e ingestione SBOM. Le tre letture/apertura rispondono anche nella forma breve sotto /v1. Ogni endpoint, con parametri, schemi ed esempi, è nel Riferimento API v1; il documento OpenAPI 3 grezzo è su https://api.cranotify.eu/swagger/openapi.json e la console navigabile su https://api.cranotify.eu/swagger.
GET https://api.cranotify.eu/v1/products
{"products":[ … ],"count":N}Alternative alle API
Molte integrazioni non hanno bisogno di chiavi:
- Ricevere eventi nei tuoi sistemi: il webhook firmato.
- Estrarre il registro: l’esportazione CSV, che comprende le impronte della catena di integrità.
- Estrarre i prodotti: l’esportazione CSV dell’anagrafica, con la corrispondente importazione.
- Esportare i dati dell’account: l’esportazione JSON da Area utente › Legale.