監査エクスポートを作成

POST /v1/audit-exports · 権限 audit-exports:write

条件に一致する監査レコードを、KeenAuth を信頼せずに検証できる署名付きパッケージへ書き出すジョブをキューに登録します。ジョブは 202 Accepted で返されます。続けて監査エクスポートを取得で状態を確認し、監査エクスポートをダウンロードでファイルを取得してください。

エクスポートを作成できるのは API キー（シークレットキーまたは制限付きキー）のみです。ジョブには、そのキーが requested_by として記録されます。環境はキーから決まります。

リクエスト

Idempotency-Key は必須です（16〜64 文字、A-Z a-z 0-9 _ -）。同じキーと同じボディで送信すると、最初のジョブが Idempotent-Replayed: true とともに返されます。同じキーで異なるボディを送信すると、422 idempotency_key_reuse で失敗します。SDK と CLI がこのヘッダーを自動的に設定します。

フィルターは監査イベントを一覧表示と同じです。省略したフィールドはフィルターされません。相違点は次のとおりです。

フィールド	型	説明
`stream`	string	`admin`（既定値）または `application`。
`from`	RFC 3339	下限（この値を含む）。既定値は保持期間の開始時点です。92 日の制限はありません。パッケージには最大 5,000 万行（プレースホルダーを含む）まで含められます。
`to`	RFC 3339	上限（この値を含まない）。既定値は現在時刻です。未来の時刻は指定できません。
`action`、`category`、`actor_type`、`actor_id`、`target_type`、`target_id`、`org_id`、`outcome`、`request_id`、`correlation_id`、`agent_only`		一覧のフィルターと同じです。一覧の `client` フィルターはここでは使用できません。`client` フィールドを指定すると `400 unknown_field` で失敗します。
`include_ip`	boolean	13 か月以内のレコードに、IP アドレス全体とユーザーエージェントを追加します。`audit-events:read_ip` 権限も必要です。既定値は `false` です。

{
  "stream": "admin",
  "from": "2026-07-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "action": "user."
}

環境ごとに同時に実行されるジョブは最大 3 件です（開発環境およびステージング環境では 1 件）。

レスポンス

202 Accepted と、status が queued のジョブが返されます。filter には、from と to の既定値を補った適用済みのフィルターが表示されます。recorded_before はスナップショットの上限です。この時刻より前に保存されたレコードのみがパッケージに含まれます。

{
  "id": "aex_01j9xk3m7q8r2s4t6v8w0y2z4e",
  "status": "queued",
  "filter": {
    "stream": "admin",
    "from": "2026-07-01T00:00:00Z",
    "to": "2026-10-01T00:00:00Z",
    "action": "user.",
    "category": null,
    "actor_type": null,
    "actor_id": null,
    "target_type": null,
    "target_id": null,
    "org_id": null,
    "outcome": null,
    "request_id": null,
    "correlation_id": null,
    "agent_only": false
  },
  "include_ip": false,
  "record_count": null,
  "file": null,
  "manifest_sha256": null,
  "failure_reason": null,
  "created_at": "2026-10-19T09:00:00Z",
  "started_at": null,
  "completed_at": null,
  "expires_at": null,
  "recorded_before": "2026-10-19T09:00:00Z",
  "requested_by": {"type": "api_key", "id": "key_01j9xk3m7q8r2s4t6v8w0y2z4d"}
}

エラー

すべてのエラーは、安定した code を含む application/problem+json ボディで返されます。

HTTP	`code`	発生条件
400	`malformed_request`	`Idempotency-Key` が欠けているか不正である、またはボディが有効な JSON ではありません。
400	`unknown_field`	ボディに、上記に記載のないフィールドが含まれています。
400	`invalid_filter`	監査サービスがフィルターを拒否しました（例: `to` が未来の時刻である）。
400	`range_outside_retention`	`from` または `to` が、お使いのプランの監査保持期間の外にあります。
422	`validation_failed`	フィールドが不正です（型が誤っている、タイムスタンプが不正、`to` が `from` より後ではない、未定義の列挙値、ID の形式が不正、空文字列）。
422	`idempotency_key_reuse`	`Idempotency-Key` が、異なるボディで再利用されました。
401	`unauthenticated`	API キーが欠けているか、無効または取り消し済みです。
403	`insufficient_permissions`	キーに `audit-exports:write` 権限がないか、`audit-events:read_ip` 権限がないのに `include_ip` を使用しています（`required_permissions` に両方が示されます）。または、呼び出し元が API キーではありません。
429	`rate_limited`	この環境で実行中のジョブが多すぎるか、レート制限を超えました。`Retry-After` に従ってください。
503	`service_unavailable`	依存サービスが一時的に利用できません。後で再試行してください。

例

curl https://api.eu.keenauth.com/v1/audit-exports \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-07-01T00:00:00Z", "to": "2026-10-01T00:00:00Z", "action": "user."}'

keenauth audit-exports create --from 2026-07-01T00:00:00Z --to 2026-10-01T00:00:00Z --action user.

個人データ

このエンドポイントは個人データ（監査イベント）を扱います。KeenAuth API における個人データでは、保存される内容、保持期間、削除方法を説明しています。いずれのフィールドにも、特別な種類の個人データ（健康、生体データ、宗教、政治的意見、性的指向）を送信しないでください。