Threat Alerts API

Супровід: Aether365 Team Аудиторія: Розробники Сфера: Сигнали ризику ідентичності та стримування в один клік

Threat Alerts показує активні сигнали ризику ідентичності підключеного tenant'а - ризикованих користувачів, виявлення ризиків і сповіщення безпеки - зчитані наживо з Microsoft Graph. Ви також можете стримати ризикованого користувача (відкликати сеанси та вимкнути обліковий запис) одним викликом.

Вимоги

Зчитування Threat Alerts потребує права Threat Alerts і підключення Microsoft 365 у режимі AI Pilot (сигнали ризику надходять від застосунку AI Pilot у Graph). Стримування додатково потребує права breach response. Без підключення AI Pilot endpoint читання повертає { "aiPilotConnected": false }.

Отримання сигналів загроз

Повертає найновіші сигнали ризику ідентичності. Кожне джерело отримується незалежно, тож один відсутній дозвіл чи неліцензована функція ніколи не зриває всю відповідь: таке джерело повертається порожнім зі статусом у sources.

GET /tenants/me/threats

Параметри запиту

Параметр	Тип	Опис
connectionId	string	Необов'язковий. Підключення AI Pilot для зчитування; за замовчуванням найстаріше

Приклад відповіді

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

Значення статусу джерела

Статус	Значення
ok	Сигнали успішно повернуто
needsConsent	Відсутній дозвіл Graph - надайте згоду повторно, щоб увімкнути це джерело
notLicensed	У tenant'а немає цієї можливості (наприклад, Entra ID P2 / Defender) - згода не допоможе
error	Непередбачена помилка під час отримання цього джерела

---

Стримування ризикованого користувача

Відкликає активні сеанси входу користувача та вимикає обліковий запис. Це деструктивний запис у Microsoft Graph через підключення AI Pilot; два записи незалежні, тож часткова невдача повідомляється, а не мовчки скасовується.

POST /tenants/me/threats/contain

Тіло запиту

Поле	Тип	Опис
userId	string	Користувач Microsoft 365 (object id або UPN) для стримування
connectionId	string	Необов'язковий. Підключення AI Pilot, через яке діяти

Приклад запиту

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

Приклад відповіді

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

needsReconsent має значення true, коли запис відхилено через відсутню або прострочену write consent; надайте згоду повторно та повторіть спробу.