API d'événement
L'API d’événements Specops vous permet d'intégrer des événements d'authentification et de sécurité des services Specops dans des systèmes externes tels que des plateformes SIEM, des outils de surveillance et des flux de travail d'automatisation.
L'API fonctionne par sondage. Les clients demandent de nouveaux événements à intervalles réguliers, et l'API les renvoie sous forme de flux ordonné dans le temps en utilisant une pagination basée sur un curseur, une page à la fois. Il n'y a pas de webhooks, donc une configuration typique est un petit script ou service qui fonctionne en continu et transmet chaque événement aux systèmes en aval, tels qu'un SIEM.
Chaque réponse inclut un curseur qui enregistre exactement jusqu'où vous avez lu. En envoyant ce curseur avec la prochaine requête, vous pouvez continuer à diffuser les événements sans refetcher ou retraiter les événements que vous avez déjà traités.
L'API est conçue pour prendre en charge l'ingestion continue dans des systèmes externes, pas pour des recherches historiques ad hoc ou des consultations de conformité occasionnelles. Un client typique est censé :
- récupérer des données historiques lors du démarrage initial (jusqu'à 7 jours en arrière)
- continuer à sonder pour de nouveaux événements
- gérer les réessais et la pagination
- transmettre les événements aux systèmes en aval tels qu'un SIEM
Remarque
Les clients doivent gérer la limitation de débit, sinon ils peuvent recevoir des réponses HTTP 429. Un sondage excessif peut entraîner un blocage temporaire ou d'autres mesures de limitation de débit protectrices. Voir Throttling. Nous recommandons également de dédupliquer les événements renvoyés par l'API Specops Event en utilisant eventRecordId. Voir Si le curseur est rejeté ou perdu.
Prérequis
Configuration
Les éléments suivants sont nécessaires pour commencer à utiliser l'API.
- Clé API : Depuis les pages d'administration dans Specops Authentication Web, générez une clé API pour la ressource Event API. La clé est une chaîne de 72 caractères. Stockez-la en toute sécurité et traitez-la comme un mot de passe.
-
URL de base : Utilisez l'URL de base pour le centre de données où votre clé a été émise.
Centre de données URL de base UE https://eu.eventapi.specopssoft.comUS https://eventapi.specopssoft.com
En-têtes de l'API
Les en-têtes suivants doivent être inclus dans l'appel API :
| Nom | Requis | Description |
|---|---|---|
| x-api-key | Oui | La clé API générée à partir des pages d'administration dans Specops Authentication Web. |
| Content-Type | Oui | Définir sur application/json. Requis pour chaque requête qui envoie un contenu. |
Remarque
La vérification de la connectivité (/api/v2/Ping) est le seul point de terminaison qui ne nécessite pas de clé API.
Flux de sondage attendu
Vous commencez un flux en envoyant une requête avec un horodatage from. Pour chaque requête suivante, envoyez le curseur renvoyé dans la réponse précédente. Cette même boucle de sondage rattrape les événements existants puis continue à récupérer les nouveaux, tant que la même valeur from et le curseur sont utilisés.
-
Vérifiez la connectivité (optionnel)
Paramètre Valeur Méthode GET Point de terminaison /api/v2/Ping Paramètres - Aucun
Description Confirmez que l'API est accessible avant d'envoyer du trafic authentifié. Aucune clé API requise. -
Démarrez le flux
Paramètre Valeur Méthode POST Point de terminaison /api/v2/SearchLogEvents Paramètres de contenu - from
- pageSize (optionnel)
Description Ouvrez le flux à partir d'une heure de début choisie. Envoyez fromsans curseur uniquement lors de cette première requête.fromdoit être dans les 7 derniers jours. La réponse renvoie les premiers événements plus unnextCursor. -
Continuez le flux
Paramètre Valeur Méthode POST Point de terminaison /api/v2/SearchLogEvents Paramètres de contenu - from (la même valeur utilisée à l'étape 2)
- curseur
Description Appelez à nouveau avec le même frometcurseurdéfini sur lenextCursorde la réponse précédente. Le curseur enregistre votre position exacte, donc chaque appel ne renvoie que les événements que vous n'avez pas encore vus. Répétez ce processus pour chaque requête suivante. -
Restez en direct
Lorsqu'une réponse a
hasMoreResults: false, vous avez atteint la fin des événements actuellement disponibles. Gardez lenextCursor, attendez quelques secondes, puis envoyez une autre requête en utilisant la même valeurfromet le mêmenextCursor. À mesure que de nouveaux événements arrivent, ils reprennent à partir du point où la réponse précédente s'est terminée. Rien de dupliqué, rien de manqué. Continuez cette boucle indéfiniment.Remarque
Ne changez jamais
fromou ne laissez tomber le curseur pendant la diffusion. Parce que le curseur fixe votre position,fromest autorisé à dépasser 7 jours tant que le flux reste actif. La limite de 7 jours s'applique uniquement lors du démarrage d'un nouveau flux sans curseur (étape 2). Exécutez uniquement un seul consommateur par clé API, car plusieurs consommateurs partageant la même clé entreront en concurrence et déclencheront la limite de débit.
Exemple d'une session de sondage complète
L'exemple ci-dessous parcourt un seul flux, de la première requête à rester en direct. Les valeurs de curseur sont opaques, donc elles sont montrées sous forme abrégée.
1. Ouvrez le flux : envoyez from sans curseur :
La réponse renvoie les premiers événements, hasMoreResults: true, et 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 identifie le type d'événement ; la valeur montrée ici est un exemple. Tous les champs eventDetails qui ne s'appliquent pas à un événement sont renvoyés sous forme de null.
2. Continuez : envoyez le même from et le nextCursor de la réponse précédente :
Continuez à répéter cela. Chaque réponse vous donne le prochain lot et un nouveau nextCursor — tant que hasMoreResults est true.
3. Restez en direct : lorsque vous êtes à jour, la réponse a hasMoreResults: false et un logEvents vide, mais elle inclut toujours un nextCursor :
{
"maxResultsPerPage": 100,
"hasMoreResults": false,
"nextCursor": "eyJTb3J0Ijpb...abbreviated2...Um9sbGluZyJ9",
"logEvents": []
}
Attendez quelques secondes, puis envoyez à nouveau la même requête en utilisant la même valeur from et le dernier nextCursor. Dès que de nouveaux événements sont disponibles, ils sont renvoyés et hasMoreResults devient à nouveau true. Répétez cette boucle indéfiniment.
Si le curseur est rejeté ou perdu
Vous n'avez besoin d'un redémarrage basé sur le temps que lorsque vous avez perdu votre place, par exemple, si le consommateur a redémarré sans un curseur stocké.
Pour redémarrer, ouvrez un nouveau flux (étape 2, sans curseur) avec from défini sur l'horodatage de l'événement le plus récent que vous avez déjà traité, moins quelques secondes de chevauchement. Puis reprenez la boucle à partir de l'étape 3. Le chevauchement peut renvoyer quelques événements que vous avez déjà vus, donc dédupliquez sur eventRecordId pour garder une seule copie de chaque événement. Ceci est un chemin de récupération uniquement. Pendant la diffusion normale, restez sur le curseur et ne réinitialisez pas from.
Description des paramètres de l'API
| Nom du paramètre | Description |
|---|---|
| from | L'heure de début du flux. Doit être dans les 7 derniers jours lors du démarrage d'un nouveau flux (sans curseur). Lorsqu'un curseur est fourni, continuez à envoyer le même from; il n'est pas revérifié par rapport à la fenêtre de 7 jours, donc un flux de longue durée n'est jamais forcé de se réinitialiser. |
| pageSize | Optionnel. Nombre d'événements par page (1–1000). Par défaut à 100. |
| cursor | La valeur nextCursor de la réponse précédente. Envoyez-la à chaque requête de suivi pour continuer le flux à partir de votre position exacte. |
| hasMoreResults | true lorsque plus d'événements sont disponibles maintenant, continuez à appeler immédiatement. false lorsque vous êtes à jour, gardez le curseur, attendez quelques secondes, et sondez à nouveau. |
| nextCursor | Le curseur à envoyer lors de la prochaine requête. Renvoyé à chaque réponse, y compris lorsque hasMoreResults est false, donc portez-le toujours en avant. |
| timestamp | Quand un événement s'est produit. Suivez la valeur la plus récente que vous avez traitée comme ancre de redémarrage (voir Si le curseur est rejeté ou perdu). |
| eventRecordId | Un identifiant unique pour chaque événement. Utilisez-le pour dédupliquer les événements après un redémarrage ou une récupération. |
Remarque
Tous les horodatages, y compris la valeur from dans la requête et l'timestamp sur chaque événement, utilisent le format ISO 8601 avec un fuseau horaire, par exemple 2026-05-28T12:34:56Z (UTC) ou 2026-05-28T14:34:56+02:00.
Throttling
L'API applique une limite de débit par clé. Si vous appelez trop souvent, vous recevrez une réponse HTTP 429.
Remarque
Traitez la réponse HTTP 429 comme un signal pour ralentir, pas comme un échec. Faites une pause brièvement, réessayez, et espacez un peu plus vos appels. Quelques secondes entre les cycles de requêtes suffisent.
Informations importantes
- L'API ne vous pousse jamais les événements. Il n'y a pas de webhooks, donc rien n'arrive de lui-même. Votre client doit continuer à demander (sonder) de nouveaux événements selon un calendrier.
- La diffusion normale de curseur ne renvoie pas de doublons. Tant que vous continuez à envoyer le curseur, chaque événement est renvoyé exactement une fois. Les doublons n'apparaissent qu'après un redémarrage ou une récupération, où un chevauchement temporel délibéré peut renvoyer quelques événements. Utilisez l'
eventRecordIdunique pour les supprimer afin que chaque événement soit stocké une seule fois. - Gardez votre clé API secrète. Toute personne ayant la clé peut lire vos événements. Stockez-la en toute sécurité, et faites-la tourner régulièrement ou si vous soupçonnez qu'elle a été exposée.