Threat Alerts API

Mantenido por: Aether365 Team Audiencia: Desarrolladores Alcance: Señales de riesgo de identidad y contención con un clic

Threat Alerts expone las señales de riesgo de identidad activas de un tenant conectado - usuarios de riesgo, detecciones de riesgo y alertas de seguridad - leídas en directo desde Microsoft Graph. También puedes contener a un usuario de riesgo (revocar sus sesiones y deshabilitar la cuenta) en una sola llamada.

Requisitos

Las lecturas de Threat Alerts requieren la habilitación de Threat Alerts y una conexión de Microsoft 365 en modo AI Pilot (las señales de riesgo provienen de la app AI Pilot Graph). La contención requiere además la habilitación de breach response. Sin una conexión de AI Pilot, el endpoint de lectura devuelve { "aiPilotConnected": false }.

Obtener señales de amenaza

Devuelve las señales de riesgo de identidad más recientes. Cada fuente se obtiene de forma independiente, de modo que un único permiso ausente o una función sin licencia nunca hunde toda la respuesta: esa fuente devuelve un resultado vacío con un estado en sources.

GET /tenants/me/threats

Parámetros de consulta

Parámetro	Tipo	Descripción
connectionId	string	Opcional. Conexión de AI Pilot a leer; por defecto la más antigua

Ejemplo de respuesta

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

Valores de estado de las fuentes

Estado	Significado
ok	Señales devueltas correctamente
needsConsent	Falta un permiso de Graph - vuelve a otorgar el consent para habilitar esta fuente
notLicensed	El tenant carece de la capacidad (p. ej. Entra ID P2 / Defender) - el consent no ayudará
error	Un error inesperado al obtener esta fuente

---

Contener a un usuario de riesgo

Revoca las sesiones de inicio activas del usuario y deshabilita la cuenta. Es una escritura destructiva en Microsoft Graph a través de la conexión de AI Pilot; las dos escrituras son independientes, de modo que un fallo parcial se informa en lugar de revertirse en silencio.

POST /tenants/me/threats/contain

Cuerpo de la solicitud

Campo	Tipo	Descripción
userId	string	El usuario de Microsoft 365 (object id o UPN) a contener
connectionId	string	Opcional. Conexión de AI Pilot a través de la cual actuar

Ejemplo de solicitud

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

Ejemplo de respuesta

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

needsReconsent es true cuando se rechazó una escritura porque el write-consent falta o ha expirado; vuelve a otorgar el consent y reintenta.