Riferimento API

Maintainer: Aether365 Team Destinatari: Sviluppatori e ingegneri DevOps Ambito: Panoramica della REST API di Aether365, URL di base e formato delle risposte

La API di Aether365 consente di accedere in modo programmatico ai dati delle scansioni, avviare scansioni, gestire i tenant e guidare AI Pilot: generare, esaminare e applicare la remediation automatica, leggere i segnali di rischio sull'identità e rafforzare le policy.

Gruppi di endpoint

Area	Cosa copre
Scans	Avviare ed elencare le scansioni di conformità ed esposizione
Results	Leggere i singoli controlli di una scansione
AI Pilot	Generare, esaminare e applicare piani di remediation automatici
Threat Alerts	Segnali di rischio sull'identità e contenimento utente con un clic
Policies	Leggere lo stato delle policy e rafforzare le policy della lista consentita
Tenants	Leggere e aggiornare il profilo del tenant
Connections	Gestire i tenant Microsoft 365 connessi
Scheduled Scans	Automatizzare le scansioni ricorrenti

URL di base

https://api.aether365.io

Tutti gli endpoint sono relativi a questo URL di base.

Autenticazione

L'API utilizza l'autenticazione Bearer token. Includi un token JWT valido nell'header Authorization di ogni richiesta:

Authorization: Bearer <token>

I token sono emessi dal sistema di autenticazione di Aether365. Consulta Autenticazione per i dettagli su come ottenere un token.

Formato delle risposte

Tutte le risposte API utilizzano una struttura JSON coerente.

Risposta di successo

{
  "success": true,
  "data": {}
}

Per gli endpoint di elenco:

{
  "success": true,
  "data": [],
  "meta": {
    "total": 142,
    "page": 1,
    "limit": 20
  }
}

Per gli endpoint di azione (trigger, delete):

{
  "success": true,
  "data": null
}

Risposta di errore

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {}
  }
}

Codici di stato HTTP

Codice	Significato
200	Successo
201	Risorsa creata
400	Richiesta non valida - parametri mancanti o errati
401	Autenticazione richiesta o token non valido
403	Accesso negato - violazione dell'isolamento tenant
404	Risorsa non trovata
409	Conflitto - ad esempio, una scansione è già in corso
429	Limite del piano raggiunto
500	Errore interno del server

Codici di errore

Codice	Descrizione
AUTH_MISSING_TOKEN	Header Authorization non presente
AUTH_INVALID_TOKEN	Impossibile verificare il token
AUTH_EXPIRED_TOKEN	Il token è scaduto
TENANT_NOT_FOUND	Il tenant non esiste
TENANT_NOT_CONNECTED	Admin consent Microsoft non completato
SCAN_NOT_FOUND	L'ID scansione non esiste
SCAN_ALREADY_RUNNING	Una scansione è già in corso per questo tenant
SCAN_PLAN_LIMIT_REACHED	Quota scansioni del piano attuale esaurita
VALIDATION_ERROR	Corpo della richiesta o parametri di query non validi
INTERNAL_ERROR	Errore imprevisto del server

Limiti di frequenza

L'API è limitata a 120 richieste al minuto. Il superamento del limite restituisce 429 Too Many Requests. L'header Retry-After indica quanti secondi attendere prima di riprovare.