Aller au contenu
L’IAM conçue pour l’ère de l’IA
Logo

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.com
    US 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.

Documentation de l’API avec Swagger

Specops fournit une documentation interactive pour l’API d’événements via Swagger UI. Utilisez le lien correspondant à votre région :

États-Unis

https://eventapi.specopssoft.com/swagger/

UE

https://eu.eventapi.specopssoft.com/swagger/

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.

  1. 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.

  2. 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 from sans curseur uniquement lors de cette première requête. from doit être dans les 7 derniers jours. La réponse renvoie les premiers événements plus un nextCursor.

  3. 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 from et curseur défini sur le nextCursor de 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.

  4. Restez en direct

    Lorsqu'une réponse a hasMoreResults: false, vous avez atteint la fin des événements actuellement disponibles. Gardez le nextCursor, attendez quelques secondes, puis envoyez une autre requête en utilisant la même valeur from et le même nextCursor. À 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 from ou ne laissez tomber le curseur pendant la diffusion. Parce que le curseur fixe votre position, from est 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 :

{
  "from": "2026-06-05T08:00:00Z",
  "pageSize": 100
}

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 :

{
  "from": "2026-06-05T08:00:00Z",
  "cursor": "eyJTb3J0Ijpb...abbreviated...Um9sbGluZyJ9"
}

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'eventRecordId unique 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.