Threat Alerts API

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

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

Вимоги

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

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

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

GET /tenants/me/threats

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

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

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

{
  "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	Сигнали успiшно повернуто
needsConsent	Вiдсутнiй дозвiл Graph - надайте згоду повторно, щоб увiмкнути це джерело
notLicensed	У tenant'а немає цiєї можливостi (наприклад, Entra ID P2 / Defender) - згода не допоможе
error	Непередбачена помилка пiд час отримання цього джерела

---

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

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

POST /tenants/me/threats/contain

Тiло запиту

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

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

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

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

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

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