API

Tutto ciò che il portale fa, lo fa con le API pubbliche. Non esistono percorsi privilegiati: se una cosa si vede o si fa dal portale, si può fare via API con gli stessi permessi.

Endpoint


CorellixOS	`https://api.<vostro-dominio>`
Corellix Cloud	`https://api.corellix.io`

Dove è attivo, il riferimento interattivo è su /swagger.

Autenticazione

Chiave API — per le integrazioni

Si genera dal portale (Sistema → Raccolta dati, o dalla gestione utenti) e si passa in un header:

GET /api/v1/vms HTTP/1.1
Host: api.azienda.loc
X-Api-Key: <la-vostra-chiave>

La chiave:

eredita i permessi dell’utente che l’ha creata;
è visibile una volta sola, alla creazione;
è revocabile singolarmente;
ha una scadenza configurabile.

Generate le chiavi da un utente di servizio con i soli permessi necessari. Una chiave creata da un amministratore ha permessi di amministratore.

JWT — per le sessioni

POST /api/v1/auth/login
Content-Type: application/json

{ "email": "utente@azienda.it", "password": "..." }

Risposta:

{ "token": "eyJ...", "expiresIn": 3600 }

Da usare come Authorization: Bearer <token>. Scadenza 60 minuti, rinnovabile.

Per un’integrazione, preferite la chiave API: non scade ogni ora e si revoca senza toccare un account.

Convenzioni

Versionamento nel percorso. /api/v1/.... Le modifiche non retrocompatibili introducono una versione nuova; quella precedente resta disponibile per il periodo di transizione dichiarato nelle note di rilascio.

Paginazione.

GET /api/v1/vms?page=1&pageSize=100

{
  "items": [ ... ],
  "page": 1,
  "pageSize": 100,
  "totalItems": 4271,
  "totalPages": 43
}

Filtri e ordinamento.

GET /api/v1/vms?platform=Nutanix&powerState=on&sort=name&order=asc

Date. Sempre ISO 8601 in UTC: 2026-08-01T14:30:00Z.

Errori.

{
  "error": "NotFound",
  "message": "Virtual machine 'abc-123' not found",
  "traceId": "00-4bf92f...-01"
}

Il traceId identifica la richiesta nei log della piattaforma: allegatelo a una segnalazione.

Codici di stato

Codice	Significato
200	Riuscito
201	Creato
204	Riuscito, senza contenuto
400	Richiesta non valida
401	Non autenticato
403	Autenticato ma senza permesso
404	Non trovato
409	Conflitto con lo stato corrente
429	Troppe richieste
500	Errore del server

La distinzione fra 401 e 403 è utile in diagnosi: 401 significa credenziale mancante o scaduta, 403 significa credenziale valida ma permesso assente.

Limiti di frequenza

I limiti sono per chiamante e per classe di endpoint. Al superamento:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Rispettate Retry-After. Un client che ritenta immediatamente peggiora la situazione che ha causato il limite.

Aree principali

Area	Percorso	Contenuto
Inventario	`/api/v1/vms`, `/hosts`, `/clusters`, `/datastores`, `/networks`	Gli oggetti raccolti
Correlazione	`/api/v1/correlation/...`	Il grafo unificato e le relazioni
Sessioni	`/api/v1/sessions`, `/users`	Sessioni utente unificate
Allarmi	`/api/v1/alerts`, `/incidents`	Allarmi e incidenti
Automazioni	`/api/v1/scripts`, `/executions`	Libreria ed esecuzioni
Agent	`/api/v1/agents/machines`, `/apps`, `/systeminfo`	Dati degli agent
PAM	`/api/v1/pam/...`	Accessi privilegiati
Service Desk	`/api/v1/tickets`, `/changes`, `/problems`, `/ci`	Processo e CMDB
Report	`/api/v1/reports`	Esecuzione ed export
Amministrazione	`/api/v1/users`, `/roles`, `/settings`	Configurazione

Esempi

# VM non protette da backup
curl -H "X-Api-Key: $CORELLIX_KEY" \
  "https://api.azienda.loc/api/v1/vms?backupProtected=false&pageSize=200"

# Allarmi critici attivi
curl -H "X-Api-Key: $CORELLIX_KEY" \
  "https://api.azienda.loc/api/v1/alerts?severity=critical&status=active"

# Eseguire uno script su un gruppo
curl -X POST -H "X-Api-Key: $CORELLIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scriptId":"...","targetGroup":"domain-controllers"}' \
  "https://api.azienda.loc/api/v1/scripts/execute"

Webhook

Oltre a interrogare, si può essere notificati. I webhook si configurano in Sistema → Impostazioni → Notifiche e inviano un POST JSON su allarme, incidente, esito di esecuzione o evento del Service Desk.

Il payload è firmato: verificate la firma prima di agire sul contenuto.

Corellix Platform 1.0.1