# 監査イベントを一覧表示

`GET /v1/audit-events` · 権限 `audit-events:read`

環境の監査レコードを、カーソルベースのページネーションで新しいものから順に一覧表示します。`admin` ストリームには、管理 API、ダッシュボード、プラットフォームを通じて行われた変更が含まれます。`application` ストリームには、アプリケーションが書き込んだイベントが含まれます。すべてのレコードは環境とストリームごとのハッシュチェーンの一部であるため、エクスポート（`POST /v1/audit-exports`）を使えば履歴を独立して検証できます。

環境は必ず API キーから決まります。環境を指定するパラメータはありません。

## リクエスト

| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
| `limit` | query | いいえ | 1 ページあたりの件数。1 から 100 まで。既定値は 20。 |
| `after` | query | いいえ | `list_metadata.after` から取得した不透明なカーソル（より古いレコード）。`before` と同時に指定できません。 |
| `before` | query | いいえ | `list_metadata.before` から取得した不透明なカーソル（より新しいレコード）。`after` と同時に指定できません。 |
| `stream` | query | いいえ | `admin`（既定）または `application`。 |
| `from` | query | いいえ | RFC 3339 形式の時刻。この時刻以降のレコードを返します。既定値は、保持期間の開始時刻と `to` の 92 日前のうち、新しい方です。 |
| `to` | query | いいえ | RFC 3339 形式の時刻。この時刻より前のレコードを返します。既定値は現在時刻です。`from` から `to` までの範囲は最大 92 日です。 |
| `action` | query | いいえ | `user.` や `connection.updated` のようなアクションの接頭辞。 |
| `category` | query | いいえ | `authentication`、`session`、`token`、`administration`、`provisioning`、`federation`、`authorization`、`data_access`、`security`、`key_management`、`configuration`、`application` のいずれか。 |
| `actor_type` | query | いいえ | `api_key`、`dashboard_user`、`m2m_client`、`agent`、`system` などのアクター種別。 |
| `actor_id` | query | いいえ | 記録されているとおりの正確なアクター ID（`key_…`、`usr_…`、`system:<service>`）。 |
| `target_type` | query | いいえ | `user`、`organization`、`audit_export` などのターゲット種別。 |
| `target_id` | query | いいえ | 正確なターゲット ID。`target_type` と併用する場合、両方が同一のターゲットに一致する必要があります。 |
| `org_id` | query | いいえ | 1 つの組織（`org_…`）に関するレコード。 |
| `outcome` | query | いいえ | `success`、`failure`、`denied`、`error` のいずれか。 |
| `request_id` | query | いいえ | リクエストの `Idp-Request-Id`（UUID）。 |
| `correlation_id` | query | いいえ | ワークフローの `Idp-Correlation-Id`（UUID）。 |
| `agent_only` | query | いいえ | `true` にすると、エージェントによる操作のみを返します。`actor_type` が `agent`、または空でない `act_chain` を持つものが対象です。 |
| `client` | query | いいえ | 呼び出しを行ったクライアントの種類。`mcp`（管理 MCP サーバー。`metadata.client` は `mcp/<version>`）または `cli`（KeenAuth CLI。`cli/<version>`）。この値はクライアント自身が宣言するもので、誰が操作したかの証明にはなりません。誰が操作したかを示すのはレコードのアクターです。一覧表示のみで使用でき、エクスポートには `client` フィルターはありません。 |

レコードは常に `occurred_at`（同じ場合は `id`）で並び、新しいものから順に返されます。`order` パラメータはありません（`order=desc` は受け付けられますが、それ以外の値は `validation_failed` で失敗します）。カーソルは、発行されたときと同じフィルターおよび環境でのみ有効です。総件数は返されません。

10 秒を超える検索は `422 search_too_broad` で停止します。フィルターまたは時間範囲を絞り込むか、大きな範囲の場合はエクスポートを使用してください。

## レスポンス

`200 OK`。`data` にはそのページのレコードが入ります。`list_metadata.after` はより古いレコード、`list_metadata.before` はより新しいレコードを指します（該当するレコードがない場合は `null`）。空のフィールドは `null` になります。

`ip` と `user_agent` は、キーが `audit-events:read_ip` 権限を持つ場合にのみ含まれ、作成から 13 か月以内のレコードにのみ値が入ります。この権限がない場合、これらのフィールドは完全に省略されます（マスクされた値も返されません）。`ip_prefix`、`ip_country`、`ip_asn`、`user_agent_family` は常に返されます。`prev_hash`、`org_prev_hash`、`record_hash` はパディングのない base64url 形式の SHA-256 値です。

```json
{
  "data": [
    {
      "id": "evt_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "stream": "admin",
      "seq": 4182,
      "schema_version": 1,
      "action": "user.blocked",
      "category": "administration",
      "outcome": "success",
      "reason_code": null,
      "occurred_at": "2026-10-01T08:15:42.120Z",
      "received_at": "2026-10-01T08:15:42.131Z",
      "recorded_at": "2026-10-01T08:15:42.140Z",
      "clock_anomaly": false,
      "actor_type": "api_key",
      "actor_id": "key_01j9xk3m7q8r2s4t6v8w0y2z4d",
      "act_chain": null,
      "session_id": null,
      "auth_context": null,
      "elevation_ref": null,
      "org_id": null,
      "targets": [
        {"type": "user", "id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p", "org_id": null, "name": null}
      ],
      "application_id": null,
      "ip_prefix": "203.0.113.0/24",
      "ip_country": "DE",
      "ip_asn": 64500,
      "user_agent_family": "keenauth-go",
      "request_id": "0192a6c1-7d3e-7a10-9b2c-3d4e5f607182",
      "correlation_id": null,
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "producer_service": "directory",
      "policy_ref": "perm:users:write",
      "changes": {"status": {"old": "active", "new": "blocked"}},
      "metadata": null,
      "prev_hash": "n4bQgYhMfWWaL-qgxVrQFaO_TxsrC4Is0V1sFbDwCgg",
      "org_prev_hash": null,
      "record_hash": "LCa0a2j_xo_5m0U8HTBBNBNCLXBkg7-g-YpeiGJm564"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": "<opaque cursor>"
  }
}
```

## エラー

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

| HTTP | `code` | 発生条件 |
|---|---|---|
| 400 | `invalid_cursor` | カーソルの形式が不正、またはこのリクエスト用に発行されたものではありません。 |
| 400 | `invalid_filter` | 監査サービスがフィルターを拒否しました（例：92 日を超える範囲）。 |
| 400 | `range_outside_retention` | `from` または `to` が、お使いのプランの監査保持期間の外にあります。 |
| 422 | `validation_failed` | クエリパラメータが無効です（`limit` が範囲外、時刻の形式が不正、`to` が `from` より後でない、未知の `stream`、`category`、`outcome`、ID の形式が不正、パラメータの重複、`desc` 以外の `order`）。 |
| 422 | `search_too_broad` | 検索に 10 秒を超えました。範囲を絞り込んでください。 |
| 401 | `unauthenticated` | API キーが未指定、無効、または取り消されています。 |
| 403 | `insufficient_permissions` | キーに `audit-events:read` がありません。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` に従ってください。 |
| 503 | `service_unavailable` | 依存サービスが一時的に利用できません。後で再試行してください。 |

## 例

```bash
curl "https://api.eu.keenauth.com/v1/audit-events?action=user.&from=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

```bash
keenauth audit-events list --action user. --from 2026-10-01T00:00:00Z
```

## 個人データ

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