API Reference

The 1Security REST API lets a SOC, MSSP, or SIEM pull your tenant's detections on a schedule. Three resources are exposed today:

Base URL

Authentication

Every request is authenticated with a per-tenant API key. A key is bound to one tenant and grants read access to that tenant's data only.

Creating a key

In the dashboard, go to Settings → API Keys (admin only) and choose Create API key. The full secret — 1sec_live_… — is shown once, at creation. Store it in your SIEM's credential store immediately; it cannot be retrieved again.

You can also mint a key from the server CLI for headless testing:

cd apps/server
bun src/scripts/createApiKey.ts --tenant <TENANT_ID> --name "Splunk prod"

Sending the key

Pass it as a bearer token (preferred) or via X-API-Key:

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

Scopes

Each key carries one or more read scopes. A request to an endpoint whose scope the key lacks returns 403.

Pagination

List endpoints return at most limit items (default 50, max 1000) plus an opaque cursor. To page through a result set, pass the returned nextCursor back as ?cursor=:

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

When hasMore is false, nextCursor is null and you've reached the end. For incremental polling (only new events since the last poll), filter by a time window rather than paging the whole table — see SIEM integration.

Rate limits

Keys are limited to 600 requests per minute (best-effort). Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (epoch seconds). Over the limit returns 429 with a Retry-After header.

Endpoints

GET /ping

Connection test. Returns the tenant and scopes the key maps to — use it to validate setup before wiring a connector.

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

Normalized audit/activity events. Requires logs:read.

Query parameters

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

Alerts raised by your monitoring policies. Requires monitoring-alerts:read.

Query parameters

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

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

GET /security-alerts

Defender / Sentinel-sourced alerts. Requires security-alerts:read.

Query parameters

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

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

GET /security-alerts/{id}

Full detail for a single security alert, including the raw provider payload (rawData) and recommended actions. Requires security-alerts:read. Returns 404 if the id is unknown to your tenant.

Errors

Errors use a consistent JSON shape and standard HTTP status codes:

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