API Reference

Interfejs API REST 1Security pozwala zespołom SOC, dostawcom MSSP i systemom SIEM pobierać (pull) aktywność i wykrycia z Twojego tenanta zgodnie z własnym harmonogramem. API działa wyłącznie w trybie odczytu: klucz pozwala czytać dane tenanta i nie umożliwia zmiany czegokolwiek ani w 1Security, ani w Twoim tenancie Microsoft 365.

Ta strona jest kontraktem: punkty końcowe, parametry, pola i kody błędów. Sposób podłączenia konkretnego systemu SIEM opisuje przewodnik integracji z SIEM.

Bazowy adres URL

API udostępniane jest z tej samej instancji, na której działa Twoje wdrożenie 1Security, pod prefiksem /api/v1.

We wdrożeniu BYOC lub on-premise API pozostaje wewnątrz Twojego perymetru sieciowego. Cała pozostała treść tej strony jest identyczna niezależnie od modelu wdrożenia.

Wszystkie przykłady poniżej używają adresu SaaS i zakładają, że klucz znajduje się w zmiennej środowiskowej:

export ONESEC_API_KEY="1sec_live_…"

Uwierzytelnianie

Każde żądanie jest uwierzytelniane kluczem API przypisanym do tenanta. Klucz jest powiązany dokładnie z jednym tenantem i daje dostęp do odczytu wyłącznie jego danych.

Tworzenie klucza

W panelu przejdź do Ustawienia → Klucze API i wybierz Utwórz klucz API. Zarządzanie kluczami dostępne jest wyłącznie dla administratorów.

Wybierasz nazwę, zakresy uprawnień klucza oraz opcjonalnie datę wygaśnięcia. Pełny sekret - 1sec_live_… - wyświetlany jest jednorazowo, w momencie utworzenia. 1Security przechowuje wyłącznie jego skrót kryptograficzny, więc nie da się go wyświetlić ponownie ani odtworzyć - również przez wsparcie techniczne. Skopiuj go od razu do magazynu poświadczeń swojego systemu SIEM.

Wysyłanie klucza w żądaniu

Przekaż go jako token bearer (zalecane) lub w nagłówku X-API-Key:

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  https://api.1security.ai/api/v1/ping

curl -H "X-API-Key: $ONESEC_API_KEY" \
  https://api.1security.ai/api/v1/ping

Zacznij od /ping. Punkt ten potwierdza poprawność klucza i pokazuje, do którego tenanta oraz jakich zakresów się odnosi - eliminuje to najczęstsze błędy konfiguracji, zanim zbudujesz wokół niego konektor.

Zakresy (Scopes)

Każdy klucz posiada jeden lub więcej zakresów odczytu. Żądanie do punktu końcowego, którego zakresu klucz nie posiada, zwraca 403 - nadawaj tylko te uprawnienia, których faktycznie potrzebuje integracja.

Rotacja i unieważnianie

Unieważnienie działa natychmiast - kolejne żądanie z tym kluczem zwróci 401. Aby przeprowadzić rotację bez przerwy w działaniu: utwórz klucz zastępczy, wdróż go w konektorze, potwierdź ruch na nowym kluczu w Ustawienia → Klucze API (przy każdym kluczu widoczny jest czas ostatniego użycia), a dopiero potem unieważnij stary.

Format odpowiedzi

Każda poprawna odpowiedź listowa używa tej samej koperty:

{
  "data": [
    /* … */
  ],
  "pagination": {
    "nextCursor": "eyJvIjo1MH0",
    "hasMore": true,
    "limit": 50
  }
}

Punkty końcowe zwracające pojedynczy obiekt (/ping, /security-alerts/{id}) zwracają { "data": { … } } bez bloku pagination.

Pola są jawnie wyliczone dla każdego punktu końcowego, dzięki czemu struktura odpowiedzi jest stabilna: z czasem mogą pojawiać się nowe pola, natomiast istniejące nie są usuwane ani zmieniane bez wcześniejszej informacji.

Znaczniki czasu

Wszystkie znaczniki czasu podawane są w UTC.

Punkty /logs i /security-alerts zwracają pełny format ISO-8601 (2026-06-05T09:12:44Z). Punkt /monitoring-alerts zwraca obecnie 2026-06-05 09:12:44 - ten sam moment w UTC, ale bez separatora T i bez oznaczenia strefy Z. Przyszłe wydanie ujednolici format do ISO-8601 we wszystkich punktach końcowych, dlatego parsuj wartości odpornie i traktuj te bez oznaczenia strefy jako UTC.

Paginacja

Punkty końcowe zwracające listy oddają maksymalnie limit obiektów (domyślnie 50, maksymalnie 1000) wraz z nieprzezroczystym kursorem. Aby pobrać kolejną stronę, przekaż zwróconą wartość nextCursor jako parametr ?cursor=. Kiedy hasMore wynosi false, nextCursor jest puste (null) i oznacza koniec wyniku.

Traktuj kursor jako wartość nieprzezroczystą - odsyłaj go w niezmienionej postaci. Jego kodowanie jest szczegółem implementacyjnym i będzie się zmieniać.

Aby uzyskać w pełni deterministyczne pobieranie z /logs, dodaj sort=discoveredAtAsc: ten porządek rozstrzyga remisy po identyfikatorze zdarzenia, więc każdy wiersz ma dokładnie jedną pozycję. W punktach alertowych wiersze o identycznej wartości sortowania nie mają gwarantowanej kolejności względem siebie - stosuj wąskie okna i deduplikuj po id.

Limity zapytań (Rate limits)

Klucze podlegają limitowi 600 żądań na minutę, stosowanemu per klucz w trybie best-effort. Poprawne odpowiedzi zawierają nagłówki:

Przekroczenie limitu zwraca 429 wraz z nagłówkiem Retry-After. Odpytywanie każdego punktu końcowego raz na minutę z dużą wartością limit mieści się głęboko w budżecie; limit istnieje po to, by ograniczyć skutki pętli w nieskończoność, a nie po to, by kształtować normalny ruch integracyjny.

Endpoints (Punkty końcowe)

GET /ping

Test połączenia. Zwraca tenanta i zakresy, do których odnosi się klucz. Nie wymaga żadnego konkretnego zakresu - działa każdy poprawny klucz.

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  https://api.1security.ai/api/v1/ping

{
  "data": {
    "tenantId": "01H…",
    "keyId": "01J…",
    "name": "Splunk prod",
    "scopes": ["logs:read", "monitoring-alerts:read", "security-alerts:read"]
  }
}

GET /logs

Znormalizowane zdarzenia aktywności M365, wzbogacone o aktora, zasób, aplikację, urządzenie i lokalizację ustalone przez 1Security. Wymaga logs:read.

Dla każdego zdarzenia zapisywane są dwa różne czasy, a różnica między nimi ma znaczenie przy odpytywaniu:

• occurredAt - kiedy akcja wydarzyła się w Microsoft 365.
• discoveredAt - kiedy 1Security przyjął zdarzenie. M365 potrafi ujawniać zdarzenia ze znacznym opóźnieniem, dlatego to właśnie po tym polu należy odpytywać. Zdarzenie opóźnione ma stary occurredAt, ale bieżący discoveredAt.

Parametry zapytania

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  "https://api.1security.ai/api/v1/logs?severity=high,critical&limit=100"

{
  "data": [
    {
      "id": "01J…",
      "occurredAt": "2026-06-05T09:12:44Z",
      "discoveredAt": "2026-06-05T09:13:01Z",
      "action": "FileDownloaded",
      "description": "Downloaded Q3-forecast.xlsx",
      "severity": "high",
      "actorId": "01H…",
      "actorName": "jane@contoso.com",
      "actorType": "user",
      "actorIp": "20.42.0.0",
      "resourceId": "01H…",
      "resourceName": "Q3-forecast.xlsx",
      "resourceType": "file",
      "workload": "SharePoint",
      "sourceType": "azure",
      "sourceName": "Microsoft 365",
      "clientApp": "OneDrive Sync",
      "deviceId": "01H…",
      "deviceName": "LAPTOP-4471",
      "isManagedDevice": false,
      "applicationId": "01H…",
      "applicationClientId": "ab12…",
      "applicationDisplayName": "Microsoft SharePoint",
      "externalEventId": "…"
    }
  ],
  "pagination": { "nextCursor": "eyJvIjoxMDB9", "hasMore": true, "limit": 100 }
}

Pola odpowiedzi: id, occurredAt, discoveredAt, action, description, severity, actorId, actorName, actorType, actorIp, resourceId, resourceName, resourceType, workload, sourceType, sourceName, clientApp, deviceId, deviceName, applicationId, applicationClientId, applicationDisplayName, isManagedDevice, externalEventId.

GET /monitoring-alerts

Alerty wygenerowane przez Twoje reguły monitorowania. Wymaga monitoring-alerts:read.

Parametry zapytania

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  "https://api.1security.ai/api/v1/monitoring-alerts?severity=high&isResolved=false&limit=50"

Pola odpowiedzi: id, name, severity, status, isResolved, resourceType, resources, assignedUser, description, createdFrom, lastScan, resolvedAt, snoozedAt.

GET /security-alerts

Alerty pochodzące z Microsoft Defender / Sentinel, powiązane z użytkownikami, grupami, wiadomościami i aplikacjami, które dopasował do nich 1Security. Wymaga security-alerts:read.

Parametry zapytania

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  "https://api.1security.ai/api/v1/security-alerts?severity=high&status=new"

Pola odpowiedzi: id, title, description, severity, status, classification, category, threatDisplayName, firstActivityDateTime, isResolved, users, groups, emails, apps.

GET /security-alerts/{id}

Pełne szczegóły pojedynczego alertu bezpieczeństwa. Wymaga security-alerts:read. Zwraca 404, jeśli identyfikator nie istnieje w Twoim tenancie.

Używaj tego punktu do wzbogacania alertu, który jest już w SIEM: prześlij podsumowanie z punktu listowego, a pełne szczegóły pobierz na żądanie podczas triage'u, zamiast indeksować cały ładunek dla każdego alertu.

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  https://api.1security.ai/api/v1/security-alerts/01J…

Pola odpowiedzi: wszystko z punktu listowego oraz determination, assignedTo, alertWebUrl, incidentWebUrl, serviceSource, detectionSource, createdDateTime, lastUpdateDateTime, resolvedDateTime, lastActivityDateTime, recommendedActions, actorDisplayName, threatFamilyName oraz rawData - oryginalny, niezmodyfikowany ładunek dostawcy.

Błędy serwera (Errors)

Błędy mają spójną strukturę JSON i standardowe kody HTTP:

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Invalid, expired, or revoked API key."
  }
}

Ograniczenia obecnej wersji API

Wprost o tym, czego jeszcze nie ma, abyś mógł to uwzględnić w projekcie integracji:

• Brak wypychania danych. Subskrypcje webhooks są planowane; dziś obowiązuje odpytywanie.
• Brak zapisu. Alertów nie da się potwierdzić ani zamknąć przez API. Synchronizacja dwukierunkowa jest planowana.
• Jeden tenant na klucz. Dostawcy MSSP obsługujący wiele tenantów potrzebują dziś osobnego klucza dla każdego z nich. Klucze na poziomie organizacji są planowane.
• Trzy zasoby. Anomalie, historia działań naprawczych i wyszukiwanie encji nie są jeszcze udostępnione.

Dalej