Threat Alerts API

Maintained by: Aether365 Team Audience: Developers Scope: Identity-risk signals and one-click containment

Threat Alerts surfaces a connected tenant's active identity-risk signals - risky users, risk detections, and security alerts - read live from Microsoft Graph. You can also contain a risky user (revoke sessions and disable the account) in one call.

Requirements

Threat Alerts reads require the Threat Alerts entitlement and a Microsoft 365 connection in AI Pilot mode (the risk signals come from the AI Pilot Graph app). Containment additionally requires the breach response entitlement. Without an AI Pilot connection the read endpoint returns { "aiPilotConnected": false }.

Get Threat Signals

Returns the most recent identity-risk signals. Each source is fetched independently, so a single missing permission or unlicensed feature never sinks the whole response - that source returns empty with a status in sources.

GET /tenants/me/threats

Query Parameters

Parameter	Type	Description
connectionId	string	Optional. AI Pilot connection to read; defaults to the oldest one

Example Response

{
  "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"
    }
  }
}

Source status values

Status	Meaning
ok	Signals returned successfully
needsConsent	A Graph permission is missing - re-grant consent to enable this source
notLicensed	The tenant lacks the capability (e.g. Entra ID P2 / Defender) - consent won't help
error	An unexpected error fetching this source

---

Contain a Risky User

Revokes the user's active sign-in sessions and disables the account. This is a destructive Microsoft Graph write through the AI Pilot connection; the two writes are independent, so a partial failure is reported rather than silently rolled back.

POST /tenants/me/threats/contain

Request Body

Field	Type	Description
userId	string	The Microsoft 365 user (object id or UPN) to contain
connectionId	string	Optional. AI Pilot connection to act through

Example Request

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" }'

Example Response

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

needsReconsent is true when a write was rejected because write consent is missing or expired; re-grant consent and retry.