Authentication¶

Noctuary uses Bearer token authentication. Pass your API key in the Authorization header on every request.

curl https://api.noctuary.io/v1/incidents \
  -H "Authorization: Bearer noc_ro_your_key_here"

Key types¶

Type	Prefix	Used by
Ingest	`noc_ingest_`	Agents — can send events and register
Read-only	`noc_ro_`	Dashboards, scripts, monitoring — read access only

Ingest keys¶

Ingest keys are required by the Noctuary Agent. They grant permission to:

POST /v1/agents/register
POST /v1/agents/{id}/heartbeat
POST /v1/events

Ingest keys cannot be used to read incidents, services, or other management endpoints.

Read-only keys¶

Read-only keys grant access to all GET endpoints and management endpoints (creating additional keys, configuring integrations). They cannot ingest events.

Creating keys¶

DashboardAPI

Settings → API Keys → Create key

Choose the key type and click Create. Copy the key — it is shown once only.

curl -X POST https://api.noctuary.io/v1/api-keys \
  -H "Authorization: Bearer noc_ro_your_key" \
  -H "Content-Type: application/json" \
  -d '{"key_type": "ingest"}'

Response:

{
  "id": "72a61fcd-e752-4d0d-91d4-bbf1dd5687c4",
  "key": "noc_ingest_Ahus1HKe7zvPk4ny4R5NtH3v...",
  "prefix": "noc_ingest_A",
  "key_type": "ingest",
  "created_at": "2026-05-31T11:58:25Z"
}

Warning

The key field is returned once only at creation time. Store it securely.

Revoking keys¶

DashboardAPI

Settings → API Keys → Revoke (icon next to the key)

curl -X DELETE https://api.noctuary.io/v1/api-keys/{id} \
  -H "Authorization: Bearer noc_ro_your_key"

Returns 204 No Content on success.

Errors¶

Response	Cause
`401 Unauthorized`	Key missing, malformed, or revoked
`403 Forbidden`	Key valid but wrong type (e.g. using a read-only key to ingest events)