API Reference

REST endpoints · Automation · Ops

For the full endpoint list and examples, go straight to Docs → API Endpoints.

Connect with an API key — no separate login

Enter the key issued after purchase on the hosted dashboard, or send it in an Authorization: Bearer header to permitted hosted APIs. Your own applications can connect through HTTP or custom code without a login session or SDK.

For a self-hosted engine, configure your own ONESEC_API_KEY or server.api_keys and use that key on the engine’s URL. A purchased hosted key is not automatically a local engine credential. Event submission needs a write key; a read-only key can query schemas, status and alerts.

See setup and curl/Python examples, including the separate instance credential used for optional cloud reporting.

The self-hosted API listens on loopback by default. Keep /health open for probes, and configure API keys before exposing any other endpoint to a network.

Self-hosted engine endpoints

GET /health - unauthenticated health probe
GET /api/v1/status — engine status
POST /api/v1/events — ingest canonical events
POST /api/v1/access/check — trusted gateway management-access decision; requires a write key and configured source/operator policy
GET /api/v1/alerts — alert feed
GET /api/v1/metrics — routing/ops metrics
GET /api/v1/event-schemas — schema spec
GET /api/v1/config - redacted engine configuration

Access checks are for trusted gateways that independently verify operator identity and derive the actual client address. Forward only after HTTP 200 and an explicit allow; deny on errors or timeouts. See the gateway integration contract.

Hosted dashboard APIs live at https://1-sec.dev/api/v1. Their /ingest endpoint receives heartbeats, enforcement records and correlations; it does not accept the local engine’s raw SecurityEvent format. Enroll a dedicated instance key through /keys before machine reporting. Keep owner keys for account access and remote commands explicitly disabled unless deliberately configured.