03 — API 參考

Ingest 端點

Base URL https://audit.example.com。所有 ingest 路由都需要具 audit.writer 角色的有效 Bearer JWT。

Method	Path	用途	狀態碼
POST	/v1/audit-logs:batch	附加最多 500 筆事件	202
POST	/v1/audit-logs	附加單筆事件	202
GET	/v1/audit-logs?source=&actor=&from=&to=	查詢（reader 角色）	200
GET	/healthz · /readyz	Liveness / readiness（不需驗證）	200

Request · POST /v1/audit-logs

Authorization: Bearer eyJ…
Idempotency-Key: 5f3c…
Content-Type: application/json

Idempotency-Key 為選填。

{
  "event_id": "a1b2-uuid",
  "occurred_at": "2026-06-27T10:14:02Z",
  "source_system": "vault",
  "source_instance": "vault-prod-eu",
  "action": "ssh.cred.issued",
  "outcome": "SUCCESS",
  "severity": "INFO",
  "actor_id": "svc-deploy",
  "target_id": "db-prod-3",
  "correlation_id": "trace-9f2c",
  "metadata": { "ttl": 3600, "role": "readonly" }
}

received_at 與 ingest_client_id 由 API 補齊。

Response · 202 Accepted

{
  "accepted": 1,
  "event_ids": ["a1b2-uuid"],
  "status": "queued"
}

錯誤 envelope（4xx/5xx）：

{
  "error": {
    "code": "invalid_argument",
    "field": "occurred_at",
    "message": "must be RFC3339"
  }
}

:batch 回 207 Multi-Status（逐筆 accepted / rejected）。