Riferimento API v1
L’API pubblica di CRAnotify è una superficie B2B ristretta e deliberata: registra un segnale di sicurezza in ingresso, legge il catalogo prodotti e il punteggio di conformità, e riceve le distinte base dalle pipeline. Restituisce sempre JSON. Ogni chiamata è autenticata con una chiave API della tua organizzazione ed è limitata a quella organizzazione: una chiave non vede mai i dati di un altro cliente, e il tenant arriva dalla chiave, mai dal corpo della richiesta. Per esplorare gli endpoint in modo interattivo usa la console su https://api.cranotify.eu/swagger, generata dalla stessa specifica OpenAPI 3 (https://api.cranotify.eu/swagger/openapi.json).
Guida alle chiavi. Creazione, permessi, rotazione e revoca delle chiavi sono descritti in API e chiavi di integrazione. Qui si documenta il contratto degli endpoint.
Indirizzo di base
In produzione l’API risponde sull’host dedicato api.<dominio>. Le tre letture e l’apertura di un incidente rispondono lì anche nella forma breve /v1:
https://api.cranotify.eu/v1/productsSu ogni host (compreso quello unificato di sviluppo) gli stessi endpoint rispondono sotto il prefisso completo /api/v1/external. L’ingestione delle distinte base è disponibile solo in questa forma completa. La specifica scaricata riporta l’indirizzo dell’host che l’ha servita.
Autenticazione
Presenta la chiave nell’header X-CRA-API-Key oppure come bearer token. I due modi sono equivalenti.
X-CRA-API-Key: cra_live_…
# in alternativa
Authorization: Bearer cra_live_…Sugli endpoint di lettura sono ammessi solo GET; l’apertura di un incidente e l’ingestione SBOM accettano solo POST. Un metodo diverso riceve 405.
Permessi (scope)
Ogni chiave porta uno o più permessi; il permesso richiesto è specifico dell’endpoint. Non esistono chiavi «tuttofare»: una chiave di sola lettura non può aprire un incidente né inviare una SBOM.
| Permesso | Sblocca |
|---|---|
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 una distinta base dalle pipeline. |
Endpoint
La superficie pubblica è composta da quattro endpoint. Non c’è impaginazione: gli elenchi tornano interi con il loro conteggio.
| Metodo e percorso | Permesso | Descrizione |
|---|---|---|
POST /api/v1/external/incidents | incidents:write | Registra un segnale di sicurezza in ingresso (INCOMING). Non crea un caso: nessuna awareness, nessun orologio 24h/72h. La trasformazione in caso è una decisione umana nella console. |
GET /api/v1/external/products | products:read | Catalogo prodotti con stato della distinta base e livello di rischio derivato dai casi attivi. Risponde {"products":[…],"count":N}. |
GET /api/v1/external/compliance-score | compliance:read | KPI di conformità in tempo reale: CRA Health Score a regole, MTTN medio, copertura SBOM, timer 24h/72h attivi. |
POST /api/v1/external/products/{sku}/sbom | products:write | Ingestione di una SBOM CycloneDX/SPDX per il prodotto indicato dallo SKU. Converge sullo stesso modello versionato per release degli upload web e CLI (vedi Distinta base). |
Sull’host dedicato api.cranotify.eu le prime tre rispondono anche nella forma breve /v1/incidents, /v1/products, /v1/compliance-score.
Non esistono endpoint di lettura dei casi, del profilo della chiave, del registro o di verifica del registro dall’API pubblica: sono operazioni della sola console. L’API non restituisce alcuna busta impaginata.
Limite di frequenza
Ogni chiave ha un limite di 100 richieste al minuto. Oltre soglia la risposta è 429 con gli header X-RateLimit-Limit, X-RateLimit-Remaining e Retry-After.
Esempi
# Catalogo prodotti
curl -H "X-CRA-API-Key: cra_live_…" https://api.cranotify.eu/v1/products
# Punteggio di conformità
curl -H "Authorization: Bearer cra_live_…" https://api.cranotify.eu/v1/compliance-score
# Apertura di un segnale in ingresso
curl -X POST -H "X-CRA-API-Key: cra_live_…" -H "Content-Type: application/json" \
-d '{"title":"…","description":"…"}' \
https://api.cranotify.eu/v1/incidents
# Invio di una SBOM per uno SKU
curl -X POST -H "X-CRA-API-Key: cra_live_…" -H "Content-Type: application/json" \
--data-binary @sbom.cyclonedx.json \
https://api.cranotify.eu/api/v1/external/products/SKU-123/sbomChe cosa l’API non espone
Il catalogo prodotti riporta metadati e stato di conformità, mai i segreti dell’organizzazione. L’identità e il recapito di chi ha segnalato una vulnerabilità, le note del Privilege Vault, i segreti TOTP e le chiavi di archiviazione non sono raggiungibili dall’API pubblica.
Codici di errore
| Codice | Significato |
|---|---|
401 | Chiave assente, errata, revocata o scaduta. |
403 | Chiave valida ma priva del permesso richiesto. |
405 | Metodo non ammesso sull’endpoint. |
422 | Corpo non valido: campi mancanti sull’apertura di un incidente, oppure SBOM che non è né CycloneDX né SPDX. |
429 | Limite di frequenza superato (100/min per chiave). |
Specifica e console API
https://api.cranotify.eu/swagger (/docs resta un alias) mostra ogni endpoint, i parametri, gli schemi e gli esempi. È servita da noi, senza CDN.https://api.cranotify.eu/swagger/openapi.json — importalo in Postman, Insomnia o in un generatore di client.