Threat Alerts API

Betreut von: Aether365 Team Zielgruppe: Entwickler Umfang: Signale zu Identitätsrisiken und Eindämmung per Klick

Threat Alerts macht die aktiven Identitätsrisiko-Signale eines verbundenen Tenants sichtbar - riskante Benutzer, Risikoerkennungen und Sicherheitswarnungen - live aus Microsoft Graph gelesen. Sie können einen riskanten Benutzer zudem in einem einzigen Aufruf eindämmen (Sitzungen widerrufen und das Konto deaktivieren).

Voraussetzungen

Lesezugriffe von Threat Alerts erfordern die Threat Alerts-Berechtigung sowie eine Microsoft 365-Verbindung im AI Pilot-Modus (die Risikosignale stammen aus der AI Pilot Graph-App). Die Eindämmung erfordert zusätzlich die Breach-Response-Berechtigung. Ohne eine AI-Pilot-Verbindung gibt der Lese-Endpunkt { "aiPilotConnected": false } zurück.

Bedrohungssignale abrufen

Gibt die neuesten Identitätsrisiko-Signale zurück. Jede Quelle wird unabhängig abgerufen, sodass eine einzelne fehlende Berechtigung oder eine nicht lizenzierte Funktion nie die gesamte Antwort zunichtemacht - diese Quelle liefert ein leeres Ergebnis mit einem Status in sources.

GET /tenants/me/threats

Abfrageparameter

Parameter	Typ	Beschreibung
connectionId	string	Optional. AI-Pilot-Verbindung zum Lesen; standardmäßig die älteste

Beispielantwort

{
  "success": true,
  "data": {
    "aiPilotConnected": true,
    "msTenantId": "00000000-0000-0000-0000-000000000000",
    "riskyUsers": [{ "id": "...", "userPrincipalName": "user@contoso.com", "riskLevel": "high" }],
    "riskDetections": [],
    "securityAlerts": [],
    "sources": {
      "riskyUsers": "ok",
      "riskDetections": "ok",
      "securityAlerts": "notLicensed"
    }
  }
}

Quellen-Statuswerte

Status	Bedeutung
ok	Signale erfolgreich zurückgegeben
needsConsent	Eine Graph-Berechtigung fehlt - erteilen Sie den Consent erneut, um diese Quelle zu aktivieren
notLicensed	Dem Tenant fehlt die Fähigkeit (z. B. Entra ID P2 / Defender) - Consent hilft nicht
error	Ein unerwarteter Fehler beim Abrufen dieser Quelle

---

Einen riskanten Benutzer eindämmen

Widerruft die aktiven Anmeldesitzungen des Benutzers und deaktiviert das Konto. Dies ist ein destruktiver Microsoft Graph-Schreibvorgang über die AI-Pilot-Verbindung; die beiden Schreibvorgänge sind unabhängig, sodass ein teilweiser Fehlschlag gemeldet und nicht still zurückgerollt wird.

POST /tenants/me/threats/contain

Anfragekörper

Feld	Typ	Beschreibung
userId	string	Der einzudämmende Microsoft 365-Benutzer (Objekt-ID oder UPN)
connectionId	string	Optional. AI-Pilot-Verbindung, über die gehandelt wird

Beispielanfrage

curl -X POST https://api.aether365.io/tenants/me/threats/contain \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "userId": "user@contoso.com" }'

Beispielantwort

{
  "success": true,
  "data": {
    "userId": "user@contoso.com",
    "connectionId": "conn_abc123",
    "disabled": true,
    "sessionsRevoked": true,
    "needsReconsent": false
  }
}

needsReconsent ist true, wenn ein Schreibvorgang abgelehnt wurde, weil der Write-Consent fehlt oder abgelaufen ist; erteilen Sie den Consent erneut und versuchen Sie es noch einmal.