Watch由 Tensor Dynamics 打造

Sentinel API v1

從第一個 API 呼叫到正式環境

Authentication

用 Bearer API key 驗證請求

除了 /healthz、/readyz 與公開 OpenAPI 文件，所有 /v1 請求都需要 API key。把 key 當成密碼，只保存在伺服器端。

先分清楚：人的登入與 API 驗證

人員先在網站登入、提交組織存取申請，核准後取得 license 與下載權。license 啟用 Sentinel server。下方 Bearer key 是該 server 發給第三方系統的機器憑證，不是人員帳號，也不能用來登入網站或桌面 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

第一次部署時，以 SENTINEL_API_KEY 設定至少 32 字元的隨機 bootstrap key。正式環境應使用 bootstrap key 建立具最小權限的可撤銷 key，再把 bootstrap key 放入密鑰管理系統。

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

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

建立可撤銷的 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
  }'

token 只會在建立回應中出現一次；回應（包含 idempotent replay）使用 Cache-Control: no-store。請立即存進密鑰管理系統。GET /v1/api-keys 只回傳 metadata，DELETE /v1/api-keys/{key_id} 會撤銷後續存取。

請求 Header

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

每個回應都帶 X-Request-ID。你可以提供合規的 request ID 來串接自己的 log；若不提供，Sentinel 會產生一個。

最小權限 Scope

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

環境 bootstrap key 用於初始管理。每個第三方整合都應使用自己的最小權限 key；部署版本的 /v1/openapi.json 是端點與 scope 的最終依據。

錯誤

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_..."
}
不要把 API key 放在瀏覽器、行動 App、URL query string、RTSP URL 或 webhook body。第三方前端應呼叫自己的後端，再由後端呼叫 Sentinel。