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. Wersja maszynowa dostępna jest pod GET /api/v1/openapi.json (OpenAPI 3.1, bez uwierzytelniania) - można ją zaimportować do Postmana lub generatora klientó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. Zwykły klucz jest powiązany dokładnie z jednym tenantem i daje dostęp do odczytu wyłącznie jego danych; klucz dla całej organizacji (MSSP) czyta dowolnego tenanta swojej organizacji, wybieranego przy każdym żądaniu.

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. W panelu wielu tenantów („Wszyscy tenanci") wskazujesz też, dla którego tenanta członkowskiego jest klucz - klucz zawsze jest powiązany z jednym tenantem, więc zgrupowany panel potrzebuje po jednym kluczu na członka (albo jednego klucza dla całej organizacji); tabela kluczy pokazuje klucze wszystkich członków z kolumną tenanta. 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ę.

Klucze dla całej organizacji (MSSP)

Dostawca MSSP lub partner obsługujący wiele tenantów w ramach jednej organizacji może zamiast osobnego klucza dla każdego tenanta utworzyć jeden klucz dla całej organizacji: w oknie tworzenia klucza zaznacz Klucz dla całej organizacji (MSSP) (opcja widoczna tylko dla kont pracujących w kontekście organizacji).

Klucz organizacyjny wybiera docelowego tenanta przy każdym żądaniu nagłówkiem X-Tenant-Id - identyfikatorem 1Security albo identyfikatorem tenanta Azure:

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  -H "X-Tenant-Id: <id tenanta lub id tenanta Azure>" \
  "https://api.1security.ai/api/v1/detections"

GET /tenants zwraca listę tenantów dostępnych dla klucza, więc integracja iteruje: pobierz listę, potem odpytuj każdego tenanta z jego identyfikatorem w nagłówku. Zasady:

• Żądanie danych bez X-Tenant-Id zwraca 400 TENANT_REQUIRED; bez wybranego tenanta działają tylko /ping i /tenants.
• Tenant spoza organizacji klucza zwraca 403 TENANT_NOT_IN_ORGANIZATION - granicą autoryzacji jest członkostwo w organizacji.
• Bramka planu obowiązuje per wybrany tenant, a limit żądań pozostaje per klucz - wszystkie tenanty dzielą jeden budżet.
• Ten sam nagłówek działa na punkcie końcowym MCP: jeden wpis serwera MCP na tenanta, każdy z własnym X-Tenant-Id.

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. Klucz organizacyjny bez wybranego tenanta zwraca tenantId: null.

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"],
    "organizationWide": false
  }
}

GET /tenants

Tenanci dostępni dla tego klucza. Klucz zwykły zwraca swojego jedynego tenanta; klucz organizacyjny - każdego tenanta swojej organizacji, czyli identyfikatory, po których integracja iteruje nagłówkiem X-Tenant-Id. Nie wymaga żadnego konkretnego zakresu.

{
  "data": [
    { "id": "01H…", "name": "Contoso", "azureTenantId": "d3adb33f-…" }
  ]
}

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 /detections/{id}

Jeden epizod wykrycia w całości. Inaczej niż lista, bez bramki poziomu - wyszukiwanie po identyfikatorze odpowiada również dla epizodów poziomu informacyjnego. Wymaga detections:read.

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

Zwraca { "data": <wykrycie> } w tym samym kształcie co elementy listy, albo 404 NOT_FOUND, gdy identyfikator nie istnieje w tym tenancie.

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 /policy-scans/{id}

Jedna migawka skanu zasady w całości. Ponad kształt listy niesie policyId oraz automations (ładunek automatyzacji skanu jako zserializowany JSON). Wymaga policy-scans:read.

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

Zwraca { "data": <skan> }, albo 404 NOT_FOUND, gdy identyfikator nie istnieje w tym tenancie.

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, które dokumentuje, we wszystkich zarejestrowanych ramach (akt o AI UE, NIS2, polskie KSC i KRiBSI, RODO, DORA, ISO/IEC 42001, ISO/IEC 27001, SOC 2, NIST CSF 2.0, HIPAA). Wymaga evidence:read.

Opcjonalne parametry zapytania from i to (ISO-8601) wyznaczają objęty okres aktywności; domyślne okno to ostatnie 183 dni. Opcjonalny parametr framework (klucz z rejestru, np. dora lub iso_27001) zostawia tylko sekcje i wpisy legendy dotyczące tych ram - ten sam zawężony pakiet pobiera przycisk Eksportuj pakiet dowodów w widoku ram. Zwraca { "data": <pakiet> } bez paginacji - pakiet jest jednym dokumentem, identycznym z pobraniem 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 /compliance/status

Gotowość zgodności w trzech warstwach. requirements to wymagania - to, co organizacja robi lub mierzy - każde oceniane raz: status to met, at_risk, not_met lub - uczciwie - not_evaluated, evaluation mówi, skąd pochodzi werdykt (measured, no_data, attested, manual, not_applicable), metricsJson niesie liczby, attestation zapis poświadczenia dla obowiązków ręcznych, a articles każdy artykuł w każdych ramach, który je cytuje. frameworks wymienia wszystkie zarejestrowane ramy (akt o AI UE, NIS2, polskie KSC i KRiBSI, RODO, DORA, ISO/IEC 42001, ISO/IEC 27001, SOC 2, NIST CSF 2.0, HIPAA) z polem selected (zadeklarowane jako obowiązujące), readinessPercent i controls (artykułami), z których każdy jest wyliczony z cytowanych wymagań. changes to różnica per ramy względem ostatniej migawki. Liczniki nagłówkowe (metCount i pokrewne) liczą wymagania cytowane przez wybrane ramy, nie artykuły. To ten sam dokument, który renderuje pulpit zgodności i który utrwala cotygodniowa migawka. Wymaga evidence:read.

Nie przyjmuje parametrów. Zwraca { "data": <status> } bez paginacji - jeden dokument na wywołanie, oceniany na żywo.

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

GET /security-score

Ocena bezpieczeństwa w dwóch celowo rozdzielonych połowach. microsoft to Microsoft Secure Score tenanta w niezmienionej postaci - najnowsza dzienna migawka (currentScore, maxScore, percent), punkty poszczególnych kontroli połączone z katalogiem profili (tytuł, remediacja, actionUrl do portalu, poziom, ranga, zagrożenia), punkty odniesienia (averageComparativeScores względem wszystkich organizacji, podobnej wielkości i branży) oraz 90 dni history. oneSecurity to pomiary 1Security z obserwowanej aktywności tenanta - każda kontrola ze status, punktami score z maxScore, pomiarem w metricsJson, ścieżką actionRoute w produkcie, cytowaniami frameworkCitations do rejestru zgodności i ewentualnym stanem state (wyłączona z oceny / przejrzana). combinedPercent uśrednia dostępne połowy; tenant bez zgody SecurityEvents.Read.All nadal dostaje połowę 1Security. Wymaga evidence:read.

Nie przyjmuje parametrów. Zwraca { "data": <score> } - jeden dokument na wywołanie, połowa 1Security liczona na żywo.

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

GET /compliance/snapshots

Datowana historia migawek stojąca za /compliance/status: cotygodniowy cron i każda migawka ręczna, od najnowszej, każda z pełnym dokumentem statusu takim, jaki został utrwalony. Przechowywana seria tych migawek sama w sobie jest dowodem ciągłego nadzoru. Wymaga evidence:read.

Przyjmuje tylko limit i cursor; elementy mają id, takenAt, trigger (scheduled lub manual) oraz status (pełny dokument).

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  "https://api.1security.ai/api/v1/compliance/snapshots?limit=12"

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.

GET /users

Katalog użytkowników tenanta, dokładnie taki, jaki wylicza ekran Użytkownicy: tożsamość, status gościa, stan MFA i logowań, licencje oraz wyliczone liczniki zasięgu - dostępne pliki, linki udostępniania, dane wrażliwe, e-maile, alerty bezpieczeństwa. Wymaga users:read.

Typowe zastosowania: synchronizacja listy gości do narzędzia IGA, wzbogacanie zdarzeń SIEM o profil aktora albo przegląd „użytkowników z największym zasięgiem danych wrażliwych".

Parametry zapytania

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  "https://api.1security.ai/api/v1/users?type=externalUsers&sort=lastSignInDesc"

Pola odpowiedzi: id, name, email, emailDomain, isExternal, isSharepoint, isAdmin, roles, licenses, hasMfa, accountEnabled, signInDisabledAt, createdAt, lastSignIn, lastActivity, groupMemberships, connectedApps, accessibleFiles, sharingLinks, sensitiveInfo, filesWithSensitiveData, sensitivityLabels, filesWithSensitivityLabels, emails, emailsReceived, emailsSent, lastEmailSentAt, lastEmailReceivedAt, securityAlerts, locationCount.

GET /users/{id}

Jeden użytkownik w pełnym widoku: kształt z listy plus liczniki wyliczane na żywo przez panel w dashboardzie - sites, activityLogs (aktywność osobista), anomalies (otwarte epizody wykryć), devices. Wymaga users:read. Zwraca 404, jeśli identyfikator nie istnieje w Twoim tenancie.

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

GET /agents

Inwentarz agentów AI - każdy agent wykryty przez 1Security poprzez Entra Agent ID, tagi jednostek usługi lub katalog Copilot, wraz z pochodzeniem (origin, builder, model), licznikami uprawnień (bezpośrednie / dziedziczone / deklarowane / blokowane przez Microsoft) i wyliczonymi licznikami zasięgu (pliki, witryny, użytkownicy, e-maile, dane wrażliwe). Wymaga agents:read.

To ta sama lista, którą renderuje ekran Agenci, więc eksport z tego punktu odpowiada temu, co audytor widzi w dashboardzie.

Parametry zapytania

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  "https://api.1security.ai/api/v1/agents?permissionFlag=withBlockedPermissions"

Pola odpowiedzi: id, name, agentObjectId, appId, backingAppId, blueprintAppId, blueprintName, accountEnabled, quarantinedAt, disabledByMicrosoftStatus, engine, discoverySource, origin, builder, model, tags, createdAt, createdByName, createdInTool, owners, sponsors, fileAccessChannel, emailAccessChannel, hasTenantWideFileAccess, hasSelectedScope, hasAdminConsentForAllUsers, aiInteractions30d, directPermissionsCount, inheritedPermissionsCount, declaredPermissionsCount, blockedPermissionsCount, accessibleFilesCount, accessibleSitesCount, accessibleUsersCount, accessibleEmailsCount, sensitiveInfo.

GET /agents/{id}

Jeden agent w pełnym widoku: kształt z listy plus warstwa behawioralna manifestu - instructions (z instructionsSummary i instructionsUpdatedAt), knowledgeSources, capabilities, conversationStarters, disclaimer, discourageModelKnowledge, onlySpecifiedSources, searchesAllWebsites, referencesOrgChart, createdByUpn - oraz liczniki na żywo: potentialUserReachCount, permissionsCount, activityCount, tokens30d, anomalies. Wymaga agents:read. Zwraca 404, jeśli identyfikator nie istnieje w Twoim tenancie.

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

Tam, gdzie Microsoft nie udostępnia manifestu agenta (np. agent wykryty tylko w Entra, bez podłączonego katalogu Copilot), pola behawioralne zwracane są jako null - warstwa tożsamości i uprawnień pozostaje kompletna.

Inwentarze zasobów

Pozostałe ekrany dashboardu są wystawione jako osiem kolejnych par: paginowana lista plus szczegóły GET …/{id}. Wszystkie dzielą standardowe parametry - limit, cursor, text (wyszukiwanie po nazwach) i sort (sortowania kolumn ekranu w postaci <kolumna>Asc / <kolumna>Desc; nieznana wartość wraca do domyślnego porządku ekranu) - a każdy punkt szczegółów zwraca 404 NOT_FOUND dla identyfikatora spoza Twojego tenanta. Tabele poniżej wymieniają tylko filtry specyficzne dla punktu; maszynowe listy parametrów i pól znajdują się w GET /api/v1/openapi.json.

GET /files i GET /files/{id}

Pliki wraz z kontenerami (foldery, dyski, witryny - rozróżniane polami type i isContainer) z ekspozycją udostępnień (sharedWithAnyone, sharedExternally, sharedWithOrganization), liczbami dostępów, linkami udostępniania, wykryciami danych wrażliwych i pokryciem etykietami. Wymaga files:read. Szczegóły dodają aktywność, findings i anomalie.

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  "https://api.1security.ai/api/v1/files?hasSensitiveInfo=hasSensitiveInfo&sort=sharedExternallyDesc"

Pola odpowiedzi: id, name, type, isContainer, path, webUrl, size, files, folders, siteId, createdBy, modifiedBy, sharedWithAnyone, sharedExternally, sharedWithOrganization, usersWithAccess, usersWithEditAccess, groupsWithAccess, appsWithAccess, sharingLinks, linkAccessUsers, sensitiveInfo, totalSensitivity, sensitivityLabels, filesWithSensitivityLabels, hasProtection, emails, emailsUploaded, emailsLinked, azureId, createdAt, modifiedAt, lastActivity, discoveredAt, lastEmailShareAt; szczegóły dodają hostedAt, links, findings, activityLogs, anomalies, sensitivityScannedAt, sensitivityScanSkipReason.

GET /groups i GET /groups/{id}

Inwentarz grup - grupy M365, zabezpieczeń, dystrybucyjne, SharePoint i role katalogu, z liczbami członków i właścicieli, zasięgiem (witryny, pliki, dane wrażliwe), linkami udostępniania i aktywnością e-mail. Wymaga groups:read. Szczegóły dodają aktywność, findings i anomalie.

Pola odpowiedzi: id, name, type, isTeams, members, containedGroups, nestedMembers, nestedExternalUsers, externalUsers, totalUsers, totalExternalUsers, totalOwners, isMemberOfGroups, accessibleSites, accessibleFiles, createdAt, sharingLinks, linkAccessUsers, sensitiveInfo, sensitivityLabels, filesWithSensitivityLabels, emails, emailsReceived, emailsSent, securityAlerts, lastEmailSentAt, lastEmailReceivedAt, discoveredAt; szczegóły dodają totalLinks, findings, activityCount, anomalies.

GET /sites i GET /sites/{id}

Inwentarz witryn SharePoint / OneDrive - witryny, podwitryny, huby, witryny osobiste i witryny kanałów Teams, z liczbami dostępów, wolumenami zawartości, statusem Copilot i wykryciami danych wrażliwych. Wymaga sites:read. Szczegóły dodają aktywność, findings i anomalie.

Pola odpowiedzi: id, name, type, privacy, webUrl, subsite, isPersonalSite, isChannelSite, isFullyScanned, isBlocked, copilotEnabled, owners, usersWithAccess, directUsersWithAccess, indirectUsersWithAccess, externalUsersWithAccess, groupsWithAccess, subsites, pages, drives, lists, files, notebooks, filesSize, teamsChannels (+ podziały standard/private/shared), sensitiveInfo, sensitivityLabels, filesWithSensitivityLabels, sharingLinks, createdAt, modifiedAt, lastActivity, discoveredAt; szczegóły dodają isHubSite, isTeamsSite, channelType, links, findings, activityCount, anomalies, path.

GET /apps i GET /apps/{id}

Inwentarz aplikacji - aplikacje Entra i jednostki usługi z werdyktami dostępu do plików / użytkowników / e-maili, kanałem dostępu, klasyfikacją AI (aiNature: copilot / own_model / hybrid) i licznikami zasięgu. Wymaga apps:read. Szczegóły dodają liczby uprawnień, obiekt accessScope, aktywność, findings i anomalie.

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  "https://api.1security.ai/api/v1/apps?aiNature=any&sort=usersDesc"

Pola odpowiedzi: id, name, publisherName, description, homepage, logoUrl, registeredApplication, enterpriseApplication, addInApplication, agentApplication, managedIdentityApplication, filesAccess, usersAccess, emailsAccess, usersWithAccess, externalUsers, files, sensitiveInfo, sensitivityLabels, filesWithSensitivityLabels, accessChannel, hasTenantWideFileAccess, hasAdminConsentForAllUsers, hasSelectedScope, hasTeamsRscScope, aiNature, aiFacets, aiPlatforms, aiClassificationSource, aiConfidence, securityAlerts, firstSeenAt, lastUsedAt, discoveredAt; szczegóły dodają permissions, groups, aiProfile, accessScope, findings, activityCount, anomalies, externalUserCount, assignedUsersCount, sitesAccessCount, teamsAccessCount.

GET /devices i GET /devices/{id}

Inwentarz urządzeń - urządzenia zarejestrowane w Entra oraz wykryte z dzienników audytu („shadow"), ze stanem zgodności, zarządzania i zaufania, licznikami użycia i przypisaniem do użytkowników. Lista pokazuje żywy inwentarz; removedFromEntra=true przełącza cały widok na urządzenia usunięte z Entra. Wymaga devices:read. Szczegóły odpowiadają też dla urządzeń usuniętych i niosą removedFromGraphAt, żeby nieaktualna postawa nie uchodziła za bieżącą.

Pola odpowiedzi: id, name, operatingSystem, operatingSystemVersion, trustType, accountEnabled, recentIpAddress, isCompliant, isManaged, isRooted, isUnknown, deviceOwnership, enrollmentType, managementType, manufacturer, model, profileType, registrationStatus, externalUserKind, isExternalUser, provider, browser, signInCount, distinctUserCount, distinctAppCount, distinctIpCount, locationCount, users oraz pola czasowe createdAt, firstSeenAt, lastSeenAt, lastSignInAt, registrationDateTime, complianceExpirationDateTime, approximateLastSignInDateTime, discoveredAt, removedFromGraphAt.

GET /emails i GET /emails/{id}

Inwentarz e-maili - pojedyncze wiadomości z kierunkiem, werdyktami bezpieczeństwa (isSpam, isPhishing, isMalware), liczbami załączników i wgrań, rozbiciem odbiorców i wykryciami danych wrażliwych. Domyślnie od najnowszych; from/to filtrują po receivedAt. Wymaga emails:read. Szczegóły dodają nadawcę i listy odbiorców wg roli (toRecipients, ccRecipients, bccRecipients), długość wątku i liczniki na żywo.

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  "https://api.1security.ai/api/v1/emails?isPhishing=true&from=$(date -u -d '-7 day' +%F)"

Pola odpowiedzi: id, subject, senderEmail, mailboxId, direction, type, importance, isRead, isSpam, isPhishing, isMalware, isThreadRoot, threadLength, threadLinkSource, hasMissingParent, isBidirectional, isPossibleAutoreply, isDelegatedSend, sendingMethod, internetMessageId, conversationId, webUrl, hasAttachments, attachments, referenceAttachments, fileUploads, uniqueUploads, recipients, recipientEmails, groups, externalRecipients, internalRecipients, uniqueDomains, totalSensitivity, sensitiveInfo, liczniki trafień wg poziomu pewności, hasProtection, sensitivityLabels, securityAlerts, receivedAt, sentAt, createdAt, updatedAt, discoveredAt; szczegóły dodają sender, toRecipients, ccRecipients, bccRecipients, recipientCount, users, files, threadCount, sensitiveInfoCount, activityCount, anomalies. Treść wiadomości nigdy nie jest wystawiana.

GET /licenses i GET /licenses/{id}

Inwentarz licencji Microsoft - każde subskrybowane SKU z liczbą miejsc (allUnits, usedUnits, availableUnits, consumedUnits), liczbą przypisań i statusem. Wymaga licenses:read. Poza wspólnymi parametrami nie ma filtrów specyficznych.

Pola odpowiedzi: id, name, description, users, externalUsers, availableUnits, usedUnits, allUnits, consumedUnits, appliesTo, status, skuId, skuPartNumber.

GET /sensitive-info-types i GET /sensitive-info-types/{id}

Katalog typów danych wrażliwych - każdy SIT (z Purview i z detekcji 1Security) z zasięgiem per typ: ile plików, e-maili, witryn, grup, użytkowników, aplikacji i agentów AI aktualnie niesie lub może osiągnąć dany typ, plus pokrycie etykietami. Wymaga sensitive-info:read. Szczegóły dodają metadane wykrywania (mechanizm, progi, przykłady), deklarację ograniczenia i rozbicie zasięgu agentów per kanał.

curl -H "Authorization: Bearer $ONESEC_API_KEY" \
  "https://api.1security.ai/api/v1/sensitive-info-types?agentReach=reachableByAgents"

Pola odpowiedzi: id, name, isActive, restrictionLevel, confidenceLevel, detectionMechanism, publisher, complianceFrameworks, sites, groups, files, emails, users, apps, agents, filesWithLabel, filesWithEnforcingLabel, restrictedAt, discoveredAt; szczegóły dodają azureId, description, integrationType, dataCategory, sensitivityLevel, documentationUrl, version, parentId, isCustomVersion, confidenceThreshold, minMatchCount, proximityWindow, aiModel, aiFallbackEnabled, restrictedBy, findings, detectionConfiguration, detectionExamples oraz zasięg agentów per kanał (agentsAppBacked, agentsTenantWide, agentsAdminConsent, agentsScoped).

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 żądanie. Klucz dla całej organizacji obejmuje wszystkich tenantów organizacji, ale każde żądanie nadal dotyczy jednego tenanta wybranego nagłówkiem X-Tenant-Id - nie ma punktu końcowego agregującego dane wielu tenantów.
• Wykrycia to epizody. Kanał /detections niesie epizody incydentów i anomalii; głębsze drążenie per zasób, poza punktami szczegółów inwentarzy (np. „każdy wpis dziennika tego pliku"), odbywa się przez filtry /logs.

Dalej