# サポートアクセスを許可

`POST /v1/support-access-grants` · 権限 `support-access-grants:write`

KeenAuth のサポート担当者に、この環境への期間限定のアクセスを付与します。たとえばサポートチケットを対応している間の利用を想定しています。アクセスは読み取り専用 (`read`) か、設定変更も可能 (`read_write_config`) のいずれかです。サポート担当者がエンドユーザーのデータを書き込むことはありません。許可の利用と担当者のすべての操作は管理の監査ログに記録され、`support_access_grant.created` イベントが発行されます。許可は、直近 5 分以内に再認証した `owner` または `admin` が、ダッシュボードからのみ作成できます。API キーとマシンクライアントは `403 insufficient_permissions` を受け取ります。

## リクエスト

| フィールド | タイプ | 必須 | 説明 |
|---|---|---|---|
| `Idempotency-Key` | header | いいえ | 任意。16-64 文字の `[A-Za-z0-9_-]`。同じキーを同じボディで繰り返すと、同じ許可を返します。 |
| `scope` | string | はい | `read` (読み取り専用) または `read_write_config` (設定変更も可能)。 |
| `duration_hours` | integer | はい | 時間単位の期間。1-72。 |
| `ticket_ref` | string | はい | サポートチケットの参照: 印字可能な ASCII 文字 1-200 文字、先頭と末尾に空白なし。 |
| `allowed_regions_of_staff` | array \| null | いいえ | Enterprise のみ。これらのリージョン (`eu`, `us`) にいる担当者だけが許可を使用できます。省略または `null` の場合は制限なし。 |

リクエストボディ:

```json
{
  "scope": "read",
  "duration_hours": 24,
  "ticket_ref": "SUP-48213",
  "allowed_regions_of_staff": ["eu"]
}
```

## レスポンス

`201 Created` と新しい許可。

```json
{
  "id": "sag_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "scope": "read",
  "status": "active",
  "ticket_ref": "SUP-48213",
  "allowed_regions_of_staff": ["eu"],
  "granted_by": "du_01j9xk2p5n7q9s1t3v5w7y9z1b",
  "created_at": "2026-10-12T09:30:00.123456Z",
  "expires_at": "2026-10-13T09:30:00.123456Z",
  "revoked_at": null
}
```

## エラー

| HTTP | コード | 概要 |
|---|---|---|
| 400 | `malformed_request` | ボディが有効な JSON ではないか、`Idempotency-Key` の形式が不正です。 |
| 403 | `insufficient_permissions` | リクエストがダッシュボードから `owner` または `admin` によって行われていないか、認証情報に必要な権限がありません。 |
| 403 | `plan_feature_unavailable` | `allowed_regions_of_staff` には Enterprise プランが必要です。 |
| 422 | `validation_failed` | フィールドが無効です (`scope`、1-72 の範囲外の `duration_hours`、`ticket_ref`、`allowed_regions_of_staff`)。 |
| 422 | `idempotency_key_reuse` | `Idempotency-Key` は別のボディですでに使用されています。 |
| 401 | `unauthenticated` | 認証情報がないか、無効または失効しています。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` の時間が過ぎてから再試行してください。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できません。`Retry-After` の時間が過ぎてから再試行してください。 |

## 例

作成と取り消しはダッシュボードの操作です。ダッシュボードが送信するリクエスト:

```http
POST /v1/support-access-grants
Content-Type: application/json
Idempotency-Key: 2f1c9a7e-5b3d-4e8f-9a6c-1d2e3f4a5b6c

{
  "scope": "read",
  "duration_hours": 24,
  "ticket_ref": "SUP-48213",
  "allowed_regions_of_staff": ["eu"]
}
```