Ereignis-API
Die Specops Ereignis-API ermöglicht es Ihnen, Authentifizierungs- und Sicherheitsereignisse von Specops-Diensten in externe Systeme wie SIEM-Plattformen, Überwachungstools und Automatisierungs-Workflows zu integrieren.
Die API funktioniert durch Abfragen. Clients fordern in regelmäßigen Abständen neue Ereignisse an, und die API gibt sie als zeitlich geordneten Stream mit cursor-basierter Paginierung, eine Seite nach der anderen, zurück. Es gibt keine Webhooks, daher ist eine typische Konfiguration ein kleines Skript oder ein Dienst, der kontinuierlich läuft und jedes Ereignis an nachgelagerte Systeme wie ein SIEM weiterleitet.
Jede Antwort enthält einen Cursor, der genau aufzeichnet, wie weit Sie gelesen haben. Indem Sie diesen Cursor mit der nächsten Anfrage senden, können Sie weiterhin Ereignisse streamen, ohne Ereignisse, die Sie bereits bearbeitet haben, erneut abzurufen oder zu verarbeiten.
Die API ist darauf ausgelegt, die kontinuierliche Aufnahme in externe Systeme zu unterstützen, nicht für Ad-hoc-Historienabfragen oder gelegentliche Compliance-Abfragen. Ein typischer Client wird erwartet:
- historische Daten beim ersten Start abrufen (bis zu 7 Tage zurück)
- weiterhin nach neuen Ereignissen abfragen
- Wiederholungen und Paginierung behandeln
- Ereignisse an nachgelagerte Systeme wie ein SIEM weiterleiten
Hinweis
Clients müssen die Ratenbegrenzung handhaben, oder sie können HTTP 429-Antworten erhalten. Übermäßiges Abfragen kann zu einer vorübergehenden Sperrung oder anderen Schutzmaßnahmen zur Ratenbegrenzung führen. Siehe Drosselung. Wir empfehlen auch, Ereignisse, die von der Specops Event API zurückgegeben werden, mit eventRecordId zu deduplizieren. Siehe Wenn der Cursor abgelehnt oder verloren wird.
Voraussetzungen
Konfiguration
Folgendes ist erforderlich, um die API zu verwenden.
- API-Schlüssel: Erstellen Sie einen API-Schlüssel für die Event API-Ressource auf den Admin-Seiten in Specops Authentication Web. Der Schlüssel ist eine 72-stellige Zeichenfolge. Speichern Sie ihn sicher und behandeln Sie ihn wie ein Passwort.
-
Basis-URL: Verwenden Sie die Basis-URL für das Rechenzentrum, in dem Ihr Schlüssel ausgestellt wurde.
Rechenzentrum Basis-URL EU https://eu.eventapi.specopssoft.comUS https://eventapi.specopssoft.com
API-Header
Die folgenden Header müssen in den API-Aufruf aufgenommen werden:
| Name | Erforderlich | Beschreibung |
|---|---|---|
| x-api-key | Ja | Der API-Schlüssel, der von den Admin-Seiten in Specops Authentication Web generiert wurde. |
| Content-Type | Ja | Auf application/json setzen. Erforderlich bei jeder Anfrage, die einen Body sendet. |
Hinweis
Der Erreichbarkeitscheck (/api/v2/Ping) ist der einzige Endpunkt, der keinen API-Schlüssel erfordert.
Erwarteter Abfragefluss
Sie starten einen Stream, indem Sie eine Anfrage mit einem from-Zeitstempel senden. Für jede nachfolgende Anfrage senden Sie den Cursor, der in der vorherigen Antwort zurückgegeben wurde. Diese gleiche Abfrageschleife holt bestehende Ereignisse auf und fährt dann fort, neue zu holen, solange derselbe from-Wert und Cursor verwendet werden.
-
Erreichbarkeit prüfen (optional)
Parameter Wert Methode GET Endpunkt /api/v2/Ping Parameter - Keine
Beschreibung Bestätigen Sie, dass die API erreichbar ist, bevor Sie authentifizierten Datenverkehr senden. Kein API-Schlüssel erforderlich. -
Den Stream starten
Parameter Wert Methode POST Endpunkt /api/v2/SearchLogEvents Body-Parameter - from
- pageSize (optional)
Beschreibung Öffnen Sie den Stream ab einer gewählten Startzeit. Senden Sie fromohne einen Cursor nur bei dieser ersten Anfrage.frommuss innerhalb der letzten 7 Tage liegen. Die Antwort gibt die ersten Ereignisse plus einennextCursorzurück. -
Den Stream fortsetzen
Parameter Wert Methode POST Endpunkt /api/v2/SearchLogEvents Body-Parameter - from (derselbe Wert wie in Schritt 2)
- cursor
Beschreibung Rufen Sie erneut mit dem gleichen fromundcursorauf, der auf dennextCursoraus der vorherigen Antwort gesetzt ist. Der Cursor zeichnet Ihre genaue Position auf, sodass jeder Aufruf nur Ereignisse zurückgibt, die Sie noch nicht gesehen haben. Wiederholen Sie diesen Vorgang für jede nachfolgende Anfrage. -
Live bleiben
Wenn eine Antwort
hasMoreResults: falsehat, haben Sie das Ende der derzeit verfügbaren Ereignisse erreicht. Behalten Sie dennextCursor, warten Sie ein paar Sekunden und senden Sie dann eine weitere Anfrage mit dem gleichenfrom-Wert und dem gleichennextCursor. Wenn neue Ereignisse eintreffen, setzen sie dort fort, wo die vorherige Antwort endete. Nichts wird dupliziert, nichts wird verpasst. Fahren Sie diese Schleife unbegrenzt fort.Hinweis
Ändern Sie niemals
fromoder lassen Sie den Cursor fallen, während Sie streamen. Da der Cursor Ihre Position fixiert, darffromüber 7 Tage hinaus altern, während der Stream aktiv bleibt. Das 7-Tage-Limit gilt nur beim Starten eines neuen Streams ohne Cursor (Schritt 2). Führen Sie nur einen einzigen Verbraucher pro API-Schlüssel aus, da mehrere Verbraucher, die denselben Schlüssel teilen, konkurrieren und das Ratenlimit auslösen.
Beispiel einer vollständigen Abfragesitzung
Das folgende Beispiel führt durch einen einzelnen Stream, von der ersten Anfrage bis zum Live-Bleiben. Cursor-Werte sind undurchsichtig, daher werden sie in gekürzter Form angezeigt.
1. Den Stream öffnen: senden Sie from ohne Cursor:
Die Antwort gibt die ersten Ereignisse zurück, hasMoreResults: true, und einen 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 identifiziert den Ereignistyp; der hier gezeigte Wert ist ein Beispiel. Alle eventDetails-Felder, die nicht auf ein Ereignis zutreffen, werden als null zurückgegeben.
2. Fortsetzen: senden Sie das gleiche from und den nextCursor aus der vorherigen Antwort:
Wiederholen Sie dies. Jede Antwort gibt Ihnen das nächste Paket und einen neuen nextCursor — solange hasMoreResults true ist.
3. Live bleiben: wenn Sie aufgeholt haben, hat die Antwort hasMoreResults: false und ein leeres logEvents, aber sie enthält immer noch einen nextCursor:
{
"maxResultsPerPage": 100,
"hasMoreResults": false,
"nextCursor": "eyJTb3J0Ijpb...abbreviated2...Um9sbGluZyJ9",
"logEvents": []
}
Warten Sie ein paar Sekunden und senden Sie dann die gleiche Anfrage erneut mit dem gleichen from-Wert und dem neuesten nextCursor. Sobald neue Ereignisse verfügbar sind, werden sie zurückgegeben und hasMoreResults wird wieder true. Wiederholen Sie diese Schleife unbegrenzt.
Wenn der Cursor abgelehnt oder verloren wird
Sie benötigen nur einen zeitbasierten Neustart, wenn Sie Ihren Platz verloren haben, zum Beispiel, wenn der Verbraucher ohne gespeicherten Cursor neu gestartet wurde.
Um neu zu starten, öffnen Sie einen neuen Stream (Schritt 2, kein Cursor) mit from, das auf den neuesten Ereignis-timestamp gesetzt ist, den Sie bereits verarbeitet haben, minus ein paar Sekunden Überlappung. Setzen Sie dann die Schleife ab Schritt 3 fort. Die Überlappung kann einige Ereignisse erneut senden, die Sie bereits gesehen haben, daher deduplizieren Sie nach eventRecordId, um nur eine Kopie jedes Ereignisses zu behalten. Dies ist nur ein Wiederherstellungspfad. Während des normalen Streamings bleiben Sie auf dem Cursor und setzen from nicht zurück.
API-Parameterbeschreibung
| Parametername | Beschreibung |
|---|---|
| from | Die Startzeit des Streams. Muss innerhalb der letzten 7 Tage liegen, wenn ein neuer Stream gestartet wird (kein Cursor). Wenn ein cursor angegeben ist, senden Sie weiterhin das gleiche from; es wird nicht erneut gegen das 7-Tage-Fenster überprüft, sodass ein lang laufender Stream niemals zurückgesetzt werden muss. |
| pageSize | Optional. Anzahl der Ereignisse pro Seite (1–1000). Standardmäßig 100. |
| cursor | Der nextCursor-Wert aus der vorherigen Antwort. Senden Sie ihn bei jeder Folgeanfrage, um den Stream von Ihrer genauen Position aus fortzusetzen. |
| hasMoreResults | true, wenn jetzt mehr Ereignisse verfügbar sind, rufen Sie sofort weiter an. false, wenn Sie aufgeholt haben, behalten Sie den Cursor, warten Sie ein paar Sekunden und fragen Sie erneut ab. |
| nextCursor | Der Cursor, der bei der nächsten Anfrage gesendet werden soll. Wird bei jeder Antwort zurückgegeben, auch wenn hasMoreResults false ist, also tragen Sie ihn immer weiter. |
| timestamp | Wann ein Ereignis aufgetreten ist. Verfolgen Sie den neuesten Wert, den Sie als Neustartanker verarbeitet haben (siehe Wenn der Cursor abgelehnt oder verloren wird). |
| eventRecordId | Eine eindeutige Kennung für jedes Ereignis. Verwenden Sie sie, um Ereignisse nach einem Neustart oder einer Wiederherstellung zu deduplizieren. |
Hinweis
Alle Zeitstempel, einschließlich des from-Werts in der Anfrage und des timestamp bei jedem Ereignis, verwenden das ISO 8601-Format mit einer Zeitzone, zum Beispiel 2026-05-28T12:34:56Z (UTC) oder 2026-05-28T14:34:56+02:00.
Drosselung
Die API erzwingt ein Ratenlimit pro Schlüssel. Wenn Sie zu oft anrufen, erhalten Sie eine HTTP 429-Antwort.
Hinweis
Behandeln Sie die HTTP 429-Antwort als Signal, langsamer zu werden, nicht als Fehler. Machen Sie eine kurze Pause, versuchen Sie es erneut und verteilen Sie Ihre Anrufe etwas mehr. Ein paar Sekunden zwischen den Anforderungszyklen sind ausreichend.
Wichtige Informationen
- Die API sendet Ihnen niemals Ereignisse zu. Es gibt keine Webhooks, daher kommt nichts von selbst an. Ihr Client muss weiterhin nach einem Zeitplan nach neuen Ereignissen fragen (abfragen).
- Normales Cursor-Streaming gibt keine Duplikate zurück. Solange Sie den Cursor weiterhin senden, wird jedes Ereignis genau einmal zurückgegeben. Duplikate erscheinen nur nach einem Neustart oder einer Wiederherstellung, bei der eine bewusste zeitliche Überlappung einige Ereignisse erneut senden kann. Verwenden Sie die eindeutige
eventRecordId, um sie zu verwerfen, sodass jedes Ereignis nur einmal gespeichert wird. - Halten Sie Ihren API-Schlüssel geheim. Jeder, der den Schlüssel hat, kann Ihre Ereignisse lesen. Speichern Sie ihn sicher und wechseln Sie ihn regelmäßig oder wenn Sie vermuten, dass er offengelegt wurde.