From your first API call to production

First: human sign-in versus API authentication

A person signs in to the website, submits an organization access request, and receives license/download access after approval. The license activates a Sentinel server. The Bearer key below is a machine credential issued by that server to an integration; it is not a human account and cannot sign in to the website or desktop App.

Person: website sign-in → organization approval → license/download
Server: license key → machine activation → Sentinel starts
Integration: local API key → scoped /v1 requests

Bootstrap key

For first deployment, set a random bootstrap key of at least 32 characters in SENTINEL_API_KEY. In production, use it to create revocable, least-privilege keys, then protect the bootstrap key in a secret manager.

export SENTINEL_API_KEY="$(openssl rand -hex 32)"

curl http://localhost:8000/v1/system \
  -H "Authorization: Bearer $SENTINEL_API_KEY"

Create a revocable integration key

curl -X POST http://localhost:8000/v1/api-keys \
  -H "Authorization: Bearer $SENTINEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SOC receiver",
    "scopes": ["events:read", "incidents:read", "incidents:write"],
    "expires_in_days": 365
  }'

The token appears only in the create response, which uses Cache-Control: no-store even for an idempotent replay. Store it in a secret manager immediately. GET /v1/api-keys returns metadata only, and DELETE /v1/api-keys/{key_id} revokes subsequent access.

Request header

Authorization: Bearer <api-key>
X-Request-ID: req_my_correlation_id   # optional

Every response includes X-Request-ID. Supply a valid request ID to correlate your own logs, or let Sentinel generate one.

Least-privilege scopes

sources:read        sources:write
monitors:read       monitors:write
events:read         events:write
incidents:read      incidents:write
integrations:manage system:read
system:write        admin

The environment bootstrap key is for initial administration. Give each third-party integration its own least-privilege key; the deployed /v1/openapi.json is authoritative for endpoints and scopes.

Errors

HTTP/1.1 401 Unauthorized
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key is missing or invalid.",
    "param": null
  },
  "request_id": "req_..."
}