# 監査エクスポートを作成

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

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

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

## リクエスト

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

フィルターは [監査イベントを一覧表示](../audit-events/list.md) と同じです。省略したフィールドはフィルターされません。相違点は次のとおりです。

| フィールド | 型 | 説明 |
|---|---|---|
| `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` です。 |

```json
{
  "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` はスナップショットの上限です。この時刻より前に保存されたレコードのみがパッケージに含まれます。

```json
{
  "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` | 依存サービスが一時的に利用できません。後で再試行してください。 |

## 例

```bash
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."}'
```

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

## 個人データ

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