API Reference

Interfejs API REST 1Security pozwala rozwiązaniom typu SOC, MSSP lub SIEM na pobieranie (pull-based) wykrytych w Twoim tenancie zdarzeń w sposób zautomatyzowany. Obecnie udostępniane są trzy główne zasoby:

Bazowy adres URL

Uwierzytelnianie

Każde żądanie jest uwierzytelniane przy pomocy klucza API przypisanego do tenanta. Klucz ten daje dostęp wyłącznie do odczytu danych należących ściśle do tego jednego tenanta.

Tworzenie klucza

Na panelu nawigacyjnym 1Security przejdź do Ustawienia → Klucze API (dostępne tylko dla administratorów) i wybierz Utwórz klucz API. Pełny, sekretny klucz, zaczynający się od 1sec_live_…, jest wyświetlany tylko raz przy jego utworzeniu. Natychmiast zapisz go w magazynie poświadczeń Twojego systemu SIEM; nie będzie można go odzyskać ponownie.

Wysyłanie klucza w żądaniu

Najlepiej przesyłać klucz jako token "Bearer" w nagłówku Authorization lub w nagłówku X-API-Key:

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

Zakresy (Scopes)

Każdy klucz posiada jeden lub więcej przypisanych zakresów uprawnień odczytu. Żądanie skierowane na punkt końcowy, dla którego klucz nie posiada odpowiedniego zakresu, zwróci błąd 403.

Paginacja

Wszystkie punkty końcowe zwracające listy oddają maksymalnie limit obiektów (domyślnie 50, maksymalnie 1000) i dołączają zaszyfrowany kursor. Aby poruszać się po pozostałych stronach wyniku, do każdego następnego wywołania przekazuj zwróconą wartość z nextCursor jako argument adresowy ?cursor=:

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

Kiedy flaga hasMore wyniesie false, nextCursor będzie puste (null), oznaczając że dotarłeś na koniec wyniku. Do zapytań o nowe zdarzenia (tylko te, które nastąpiły od ostatniego odpytywania), wcale nie polegaj na paginacji po całej historii, lecz filtruj okna czasowe — szczegóły opisano w przewodniku Integracji z SIEM.

Limity zapytań (Rate limits)

Klucze podlegają limitowi do 600 zapytań na minutę. Odpowiedzi serwera zwracają do Twojego skryptu nagłówki takie jak: X-RateLimit-Limit, X-RateLimit-Remaining oraz X-RateLimit-Reset (w sekundach EPOCH). Przekroczenie zapasów wymusi zwrócenie błędu 429 wraz z nagłówkiem zwrotnym Retry-After.

Endpoints (Punkty Końcowe)

GET /ping

Testowanie połączenia. Zwraca informacje do którego tenanta i do jakich zakresów uprawnień odwołuje się Twój klucz API — użyj tego do zwalidowania pierwszej konfiguracji w Twoim konektorze SIEM.

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

Ujednolicone zdarzenia audytu/aktywności. Wymaga uprawnienia (scope): logs:read.

Parametry Query

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",
      "severity": "high",
      "actorName": "jane@contoso.com",
      "actorType": "user",
      "actorIp": "20.42.x.x",
      "resourceName": "Q3-forecast.xlsx",
      "resourceType": "file",
      "workload": "SharePoint",
      "applicationDisplayName": "Microsoft SharePoint"
    }
  ],
  "pagination": { "nextCursor": "eyJvIjoxMDB9", "hasMore": true, "limit": 100 }
}

GET /monitoring-alerts

Alerty utworzone na bazie Twoich aktywnych polityk monitorowania. Wymaga uprawnienia (scope): monitoring-alerts:read.

Parametry Query

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

Struktura każdego obiektu obejmuje m.in.: id, name, severity, status, isResolved, resourceType, resources, assignedUser, description, createdFrom, lastScan, resolvedAt, snoozedAt.

GET /security-alerts

Alerty importowane bezpośrednio ze środowiska Microsoft Defender / Sentinel. Wymaga uprawnienia (scope): security-alerts:read.

Parametry Query

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

Struktura każdego obiektu obejmuje m.in.: id, title, description, severity, status, classification, category, threatDisplayName, firstActivityDateTime, isResolved, users, groups, emails, apps.

GET /security-alerts/{id}

Pełne szczegóły pojedynczego wybranego alertu bezpieczeństwa wraz z niemodyfikowanym surowym wpisem wziętym wprost od dostawcy (rawData) i wszelkimi rekomendowanymi akcjami. Wymaga security-alerts:read. Zwraca 404, jeśli id jest błędne w danym tenancie.

Błędy serwera (Errors)

Komunikaty o błędach zawsze posługują się spójną strukturą zwrotną w formacie JSON i poprawnymi kodami odpowiedzi protokołu HTTP:

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