API de Eventos
La API de Eventos de Specops te permite integrar eventos de autenticación y seguridad de los servicios de Specops en sistemas externos como plataformas SIEM, herramientas de monitoreo y flujos de trabajo de automatización.
La API funciona mediante sondeo. Los clientes solicitan nuevos eventos a intervalos regulares, y la API los devuelve como un flujo ordenado por tiempo utilizando paginación basada en cursor, una página a la vez. No hay webhooks, por lo que una configuración típica es un pequeño script o servicio que se ejecuta continuamente y reenvía cada evento a sistemas aguas abajo, como un SIEM.
Cada respuesta incluye un cursor que registra exactamente hasta dónde has leído. Al enviar ese cursor con la siguiente solicitud, puedes continuar transmitiendo eventos hacia adelante sin volver a recuperar o reprocesar eventos que ya has manejado.
La API está diseñada para soportar la ingesta continua en sistemas externos, no para búsquedas históricas ad hoc o consultas ocasionales de cumplimiento. Se espera que un cliente típico:
- recupere datos históricos en el inicio inicial (hasta 7 días atrás)
- continúe sondeando para nuevos eventos
- maneje reintentos y paginación
- reenvíe eventos a sistemas aguas abajo como un SIEM
Nota
Los clientes deben manejar la limitación de tasa, o pueden recibir respuestas HTTP 429. El sondeo excesivo puede llevar a un bloqueo temporal u otras medidas de limitación de tasa protectoras. Ver Limitación. También recomendamos desduplicar eventos devueltos por la Specops Event API usando eventRecordId. Ver Si el cursor es rechazado o perdido.
Prerrequisitos
Configuración
Se requiere lo siguiente para comenzar a usar la API.
- Clave de API: Desde las páginas de administración en Specops Authentication Web, genera una clave de API para el recurso Event API. La clave es una cadena de 72 caracteres. Almacénala de forma segura y trátala como una contraseña.
-
URL Base: Usa la URL base para el centro de datos donde se emitió tu clave.
Centro de datos URL Base UE https://eu.eventapi.specopssoft.comEE. UU. https://eventapi.specopssoft.com
Encabezados de API
Los siguientes encabezados deben incluirse en la llamada a la API:
| Nombre | Requerido | Descripción |
|---|---|---|
| x-api-key | Sí | La clave de API generada desde las páginas de administración en Specops Authentication Web. |
| Content-Type | Sí | Configurado a application/json. Requerido en cada solicitud que envía un cuerpo. |
Nota
La verificación de accesibilidad (/api/v2/Ping) es el único punto final que no requiere una clave de API.
Flujo de sondeo esperado
Inicias un flujo enviando una solicitud con una marca de tiempo from. Para cada solicitud subsiguiente, envía el cursor devuelto en la respuesta anterior. Este mismo bucle de sondeo se pone al día con los eventos existentes y luego continúa recuperando nuevos, siempre que se utilice el mismo valor from y cursor.
-
Verificar accesibilidad (opcional)
Parámetro Valor Método GET Punto final /api/v2/Ping Parámetros - Ninguno
Descripción Confirma que la API es accesible antes de enviar tráfico autenticado. No se requiere clave de API. -
Iniciar el flujo
Parámetro Valor Método POST Punto final /api/v2/SearchLogEvents Parámetros del cuerpo - from
- pageSize (opcional)
Descripción Abre el flujo desde un tiempo de inicio elegido. Envía fromsin un cursor solo en esta primera solicitud.fromdebe estar dentro de los últimos 7 días. La respuesta devuelve los primeros eventos más unnextCursor. -
Continuar el flujo
Parámetro Valor Método POST Punto final /api/v2/SearchLogEvents Parámetros del cuerpo - from (el mismo valor usado en el paso 2)
- cursor
Descripción Llama de nuevo con el mismo fromycursorconfigurado alnextCursorde la respuesta anterior. El cursor registra tu posición exacta, por lo que cada llamada devuelve solo eventos que aún no has visto. Repite este proceso para cada solicitud subsiguiente. -
Mantenerse en vivo
Cuando una respuesta tiene
hasMoreResults: falsehas llegado al final de los eventos actualmente disponibles. Mantén elnextCursor, espera unos segundos, luego envía otra solicitud usando el mismo valorfromy el mismonextCursor. A medida que lleguen nuevos eventos, se reanudarán desde el punto donde terminó la respuesta anterior. Nada duplicado, nada perdido. Continúa este bucle indefinidamente.Nota
Nunca cambies
fromni elimines el cursor mientras transmites. Debido a que el cursor fija tu posición, se permite quefrompase de 7 días mientras el flujo permanece activo. El límite de 7 días se aplica solo al iniciar un nuevo flujo sin un cursor (paso 2). Ejecuta solo un consumidor por clave de API, porque múltiples consumidores compartiendo la misma clave competirán y activarán el límite de tasa.
Ejemplo de una sesión de sondeo completa
El ejemplo a continuación recorre un solo flujo, desde la primera solicitud hasta mantenerse en vivo. Los valores del cursor son opacos, por lo que se muestran en forma abreviada.
1. Abre el flujo: envía from sin cursor:
La respuesta devuelve los primeros eventos, hasMoreResults: true, y un nextCursor:
{
"maxResultsPerPage": 100,
"hasMoreResults": true,
"nextCursor": "eyJTb3J0Ijpb...abbreviated...Um9sbGluZyJ9",
"logEvents": [
{
"timestamp": "2026-06-05T08:01:12Z",
"eventId": "UserPasswordReset",
"eventRecordId": "9f1c8a3e-4b2d-4c7a-9b10-2f5e8d6a1c44",
"eventDetails": {
"upn": "jane.doe@contoso.com",
"ipAddress": "203.0.113.42",
"resource": "Reset Password",
"identityServiceId": "Gatekeeper"
}
}
]
}
eventId identifica el tipo de evento; el valor mostrado aquí es un ejemplo. Cualquier campo eventDetails que no aplique a un evento se devuelve como null.
2. Continuar: envía el mismo from y el nextCursor de la respuesta anterior:
Sigue repitiendo esto. Cada respuesta te da el siguiente lote y un nuevo nextCursor — mientras hasMoreResults sea true.
3. Mantenerse en vivo: cuando te hayas puesto al día, la respuesta tiene hasMoreResults: false y un logEvents vacío, pero aún incluye un nextCursor:
{
"maxResultsPerPage": 100,
"hasMoreResults": false,
"nextCursor": "eyJTb3J0Ijpb...abbreviated2...Um9sbGluZyJ9",
"logEvents": []
}
Espera unos segundos, luego envía la misma solicitud nuevamente usando el mismo valor from y el último nextCursor. Tan pronto como nuevos eventos estén disponibles, se devuelven y hasMoreResults se convierte en true nuevamente. Repite este bucle indefinidamente.
Si el cursor es rechazado o perdido
Solo necesitas un reinicio basado en el tiempo cuando has perdido tu lugar, por ejemplo, si el consumidor se reinició sin un cursor almacenado.
Para reiniciar, abre un nuevo flujo (paso 2, sin cursor) con from configurado al timestamp del evento más reciente que ya has procesado, menos unos segundos de superposición. Luego reanuda el bucle desde el paso 3. La superposición puede reenviar algunos eventos que ya has visto, por lo que desduplica en eventRecordId para mantener solo una copia de cada evento. Este es solo un camino de recuperación. Durante la transmisión normal, mantente en el cursor y no restablezcas from.
Descripción de los parámetros de la API
| Nombre del parámetro | Descripción |
|---|---|
| from | La hora de inicio del flujo. Debe estar dentro de los últimos 7 días al iniciar un nuevo flujo (sin cursor). Cuando se proporciona un cursor, sigue enviando el mismo from; no se vuelve a verificar contra la ventana de 7 días, por lo que un flujo de larga duración nunca se ve obligado a reiniciarse. |
| pageSize | Opcional. Número de eventos por página (1–1000). Por defecto es 100. |
| cursor | El valor nextCursor de la respuesta anterior. Envíalo en cada solicitud de seguimiento para continuar el flujo desde tu posición exacta. |
| hasMoreResults | true cuando hay más eventos disponibles ahora mismo, sigue llamando inmediatamente. false cuando te has puesto al día, mantén el cursor, espera unos segundos y vuelve a sondear. |
| nextCursor | El cursor para enviar en la siguiente solicitud. Devuelto en cada respuesta, incluso cuando hasMoreResults es false, así que siempre llévalo adelante. |
| timestamp | Cuando ocurrió un evento. Rastrea el valor más reciente que has procesado como un ancla de reinicio (ver Si el cursor es rechazado o perdido). |
| eventRecordId | Un identificador único para cada evento. Úsalo para desduplicar eventos después de un reinicio o recuperación. |
Nota
Todas las marcas de tiempo, incluido el valor from en la solicitud y el timestamp en cada evento, usan el formato ISO 8601 con una zona horaria, por ejemplo 2026-05-28T12:34:56Z (UTC) o 2026-05-28T14:34:56+02:00.
Limitación
La API aplica un límite de tasa por clave. Si llamas con demasiada frecuencia, recibirás una respuesta HTTP 429.
Nota
Trata la respuesta HTTP 429 como una señal para reducir la velocidad, no como un fallo. Haz una pausa breve, reintenta y espacia tus llamadas un poco más. Unos segundos entre los ciclos de solicitud son suficientes.
Información importante
- La API nunca te envía eventos. No hay webhooks, por lo que nada llega por sí solo. Tu cliente tiene que seguir preguntando (sondeando) por nuevos eventos en un horario.
- La transmisión normal de cursor no devuelve duplicados. Mientras sigas enviando el cursor, cada evento se devuelve exactamente una vez. Los duplicados solo aparecen después de un reinicio o recuperación, donde una superposición de tiempo deliberada puede reenviar algunos eventos. Usa el
eventRecordIdúnico para eliminarlos, de modo que cada evento se almacene solo una vez. - Mantén tu clave de API secreta. Cualquiera con la clave puede leer tus eventos. Almacénala de forma segura y rótala regularmente o si sospechas que ha sido expuesta.