API Connessioni

Maintainer: Aether365 Team Destinatari: Sviluppatori Ambito: Endpoint API Connessioni - gestione delle connessioni ai tenant Microsoft 365

Le connessioni rappresentano tenant Microsoft 365 collegati. Ogni connessione corrisponde a un tenant Microsoft (identificato dal suo msTenantId) a cui è stato concesso l'admin consent.

Elencare le connessioni

Restituisce tutti i tenant Microsoft 365 collegati all'account autenticato.

GET /tenants/me/connections

Richiesta di esempio

curl https://api.aether365.io/tenants/me/connections \
  -H "Authorization: Bearer <token>"

Risposta di esempio

{
  "success": true,
  "data": [
    {
      "id": "conn_abc123",
      "msTenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "label": "Contoso Production",
      "connectedAt": "2026-02-01T09:00:00Z",
      "isPrimary": true
    },
    {
      "id": "conn_def456",
      "msTenantId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "label": "Contoso Staging",
      "connectedAt": "2026-03-15T14:30:00Z",
      "isPrimary": false
    }
  ]
}

Campi della risposta

Campo	Tipo	Descrizione
id	string	Identificativo della connessione
msTenantId	string	ID tenant Microsoft Entra (GUID)
label	string	Etichetta visualizzata assegnata alla connessione
connectedAt	string	Timestamp ISO 8601 del collegamento del tenant
isPrimary	boolean	Se questo è il tenant attualmente attivo

---

Attivare una connessione

Imposta un tenant collegato come tenant attivo. Le visualizzazioni della dashboard e le chiamate API senza un filtro tenant esplicito operano sul tenant attivo.

POST /tenants/me/connections/{connectionId}/activate

Parametri del percorso

Parametro	Tipo	Descrizione
connectionId	string	L'ID della connessione da attivare

Richiesta di esempio

curl -X POST https://api.aether365.io/tenants/me/connections/conn_def456/activate \
  -H "Authorization: Bearer <token>"

Risposta di esempio

{
  "success": true,
  "data": {
    "id": "conn_def456",
    "msTenantId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
    "label": "Contoso Staging",
    "connectedAt": "2026-03-15T14:30:00Z",
    "isPrimary": true
  }
}

---

Rimuovere una connessione

Scollega un tenant Microsoft 365. Interrompe le scansioni future per questo tenant. I dati delle scansioni esistenti vengono conservati secondo la policy di conservazione.

DELETE /tenants/me/connections/{connectionId}

WARNING

Questa azione non può essere annullata. Ricollegare il tenant richiede di ripetere il flusso di admin consent.

Parametri del percorso

Parametro	Tipo	Descrizione
connectionId	string	L'ID della connessione da rimuovere

Richiesta di esempio

curl -X DELETE https://api.aether365.io/tenants/me/connections/conn_def456 \
  -H "Authorization: Bearer <token>"

Risposta di esempio

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

Errori

Codice	HTTP	Descrizione
CONNECTION_NOT_FOUND	404	Nessuna connessione con questo ID esiste per il tenant
CANNOT_REMOVE_LAST_CONNECTION	409	Non è possibile rimuovere l'unica connessione rimasta