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 → API i wybierz Utwórz klucz API. Zakładka Klucze API pokazuje każdy klucz wraz z jego zakresami, statusem i czasem ostatniego użycia. 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.

Klucze utworzone zanim /policy-scans zmienił nazwę z /monitoring-alerts mogą nadal mieć zakres monitoring-alerts:read. Nadal działa - serwer traktuje go jak policy-scans:read - ale nowe klucze powinny prosić o nową nazwę.

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 → 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 i w pełnym formacie ISO-8601 (2026-06-05T09:12:44Z) w każdym punkcie końcowym. Wcześniejsze wydania zwracały znaczniki skanów zasad bez separatora T i oznaczenia Z; to już poprawione.

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", "detections: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 /detections

Własne epizody wykryć 1Security. Wymaga detections:read.

Wiersze używają koperty rozróżnianej polem kind: pola poniżej istnieją dla każdego wykrycia, a wszystko specyficzne dla rodzaju jedzie pod details. Dziś każdy wiersz ma kind: "anomaly"; nowe rodzaje (np. podróż niemożliwa czy werdykty phishingowe) pojawią się jako nowe wartości kind z własnym kształtem details - sama koperta się nie zmienia.

Domyślnie zwracane są tylko epizody z poziomu alertowego - te, które przekroczyły linię alertu tenanta. Przekaż includeInfoTier=true, aby otrzymać także poziom informacyjny.

Parametry zapytania

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  "https://api.1security.ai/api/v1/detections?status=open&limit=50"

Pola odpowiedzi: id, kind, severity, status, stateful, openedAt, lastSeenAt, resolvedAt, summary, detector (id, name), entity (type, id, name - null dla epizodów zagregowanych na poziomie tenanta) oraz details (level, current, peakCurrent, baseline, score, peakScore, diffPercent, actionGroup, activityLabel, activityDescription, episodeCount).

summary to gotowe angielskie zdanie opisujące epizod w liczbach danego podmiotu - nadaje się jako tytuł incydentu w SIEM. activityLabel i activityDescription to czytelne dla człowieka odpowiedniki actionGroup, dzięki którym odbiorcy nie muszą samodzielnie rozszyfrowywać wartości taksonomii, takich jak privilege_granted.

GET /policy-scans

Migawki oceny zasad: każdy wiersz odnotowuje, że w chwili scannedAt zasada pasowała do resources zasobów. Wymaga policy-scans:read (klucze ze starym zakresem monitoring-alerts:read nadal działają).

To seria metryk, a nie strumień alertowy - przesyłaj ją, gdy chcesz mieć w SIEM liczniki postawy bezpieczeństwa. Zasada, której licznik po przekroczeniu progu ma kogoś powiadomić, robi to przez swoją regułę alertową, a decyzja trafia do /notifications.

Parametry zapytania

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

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

GET /notifications

Dziennik powiadomień: jeden wiersz na decyzję o powiadomieniu - wysłane, wstrzymane z powodem lub nieudane - dla podsumowań zasad, wyzwalaczy natychmiastowych i powiadomień o anomaliach. Wymaga notifications:read.

Parametry zapytania

Pola odpowiedzi: id, createdAt, source, kind, channel, decision, reason, policyId, policyName, subjectType, subjectId, subjectCount, resourceType, resourceId, severity, recipients, recipientSource, senderMode, mailSubject.

GET /evidence/agents

Pakiet dowodów zgodności dla agentów AI: jeden opatrzony datą dokument JSON obejmujący inwentarz agentów, przyznane uprawnienia, aktywność, zdarzenia cyklu życia i zagrożeń, zmiany instrukcji, agentów dostępnych do instalacji, dostęp aplikacji zewnętrznych oraz atestację przechowywania logów - każda sekcja jest przypisana do artykułów aktu o AI UE, NIS2 oraz polskich ustaw KSC i o AI, które dokumentuje. Wymaga evidence:read.

Opcjonalne parametry zapytania from i to (ISO-8601) wyznaczają objęty okres aktywności; domyślne okno to ostatnie 183 dni. Zwraca { "data": <pakiet> } bez paginacji - pakiet jest jednym dokumentem, identycznym z pobraniem Dowody zgodności w panelu.

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

Pełną strukturę pakietu, listę sekcji i mapowanie na artykuły opisuje strona Eksport dowodów zgodności.

GET /actions

Rejestr akcji naprawczych: każda akcja, którą 1Security zaplanował, administrator zatwierdził lub odrzucił, platforma wykonała, a niezależna sonda potwierdziła - wraz z wyzwalaczem (polityka lub człowiek), zakresem i bieżącym stanem uwagi. To ślad audytowy pytania "co platforma zmieniła w Microsoft 365 i kto to zatwierdził". Wymaga actions:read.

Parametry zapytania

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  "https://api.1security.ai/api/v1/actions?rung=applied&from=$(date -u -d '-30 day' +%FT%TZ)"

Pola odpowiedzi: id, actionName, actionType, policyId, policyName, actorId, actorName, actorKind, rollupRung, itemsTotal, itemsSettled, failedCount, hasFailures, isSimulated, isIrreversible, revertBucket, resourceType, resourceId, resourceName, askerCount, askerNames, actionArguments, createdAt, updatedAt, dueAt, acknowledgedAt.

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.
• Brak wyszukiwania encji. Pojedynczych użytkowników, plików, grup i aplikacji nie da się jeszcze odpytywać bezpośrednio; wykrycia obejmują na razie wyłącznie rodzaj anomalii.

Dalej