# 設定をエクスポートする

`GET /v1/config-export` · 権限 `config:read` および各エクスポート対象の種類の読み取り権限

環境の設定を、環境に依存しない 1 つのドキュメントとして返します。これにより、内容を確認したり、バージョン管理で保存したり、後で別の環境に適用したりできます。ドキュメントには環境固有の ID、バージョン、タイムスタンプ、シークレットは含まれません。リソース同士は `key` で参照し合います。同じ設定からは常にバイト単位で同一のドキュメントが生成されます（種類は下記の順序、その中では `key` 順。集合を表すリストはソートされます）。レスポンスは JSON で、これは有効な YAML でもあります。`keenauth config export` は既定で YAML を出力します。

## リクエスト

環境は認証情報から決まります。指定可能なクエリパラメータは 1 つだけで、省略可能です。

| パラメータ | 説明 |
|---|---|
| `kinds` | エクスポートする種類をカンマ区切りで指定します（例: `kinds=connection,api`）。指定しない場合はすべての種類をエクスポートします。 |

| 種類 | `key` | `config:read` 以外の権限 |
|---|---|---|
| `environment_settings` | `default` | `environment-settings:read` |
| `identity_settings` | `default` | `identity-settings:read` |
| `attack_protection` | `default` | `attack-protection:read` |
| `branding` | `default` | `branding:read` |
| `connection` | 接続 `key` | `connections:read` |
| `api` | API `key` | `apis:read`、`applications:read` |
| `role` | ロール `key` | `roles:read`、`apis:read` |
| `application` | アプリケーション `key` | `applications:read`、`apis:read`、`connections:read` |
| `application_branding` | アプリケーション `key` | `branding:read`、`applications:read` |

`api`、`role`、`application` も、参照先の種類の権限が必要です。参照は `key` に解決されるためです。`config:read` だけではリソースの読み取り権限は付与されません。

## レスポンス

`200 OK` で返され、`Cache-Control: no-store` を伴います。

- 参照には `key` を使います: `application.default_api`、`application.connections`（ボタンの順序は保持されます）、`application.api_grants[].api`、`api.introspection_applications`。
- エンタープライズ OIDC 接続は、フェデレーション用の資料を `oidc` として保持します（`issuer`、`client_id`、`client_auth_method`、`provider_profile`）。リダイレクト URI、SP ホスト、シークレットそのものは環境固有のため、エクスポートされません。`oidc` は、資料がまだ書き込まれていない場合は `null` になります。適用するドキュメントでは、`oidc: null` によって資料は変更されません。Entra のテナント ID は読み取れないため、`entra` プロファイルの接続は、現時点ではドキュメントで管理できません。
- シークレットの値はエクスポートされません。KeenAuth に指定したシークレット（ソーシャル接続またはエンタープライズ OIDC 接続の `client_secret`）は、プレースホルダー `{"secret_ref": {"source": "env", "name": "KEENAUTH_CONNECTION_<KEY>_CLIENT_SECRET"}}` として表示されます。CLI はドキュメントの適用時に、その環境変数から値を読み取ります。その他の接続は `"client_secret": null` になります。KeenAuth が発行するシークレット（アプリケーションのクライアントシークレット、API キー、Webhook 署名シークレット）と秘密鍵は、まったくエクスポートされません。移行先の環境は独自に発行します。`jwks` には公開鍵のみが含まれます。
- 組み込みのシステム API はエクスポートされません。これはすべての環境に存在します。組織が所有するアプリケーションと、クライアント自身が登録したアプリケーション（Dynamic Client Registration、Client ID Metadata Document）も同様にエクスポートされません。これらは `warnings` に、コード `resource_skipped` とともに一覧されます。
- 解決できない参照（たとえばスキップされたアプリケーションへの参照）は、ドキュメントから削除されます。その参照は、コード `reference_dropped` と JSON の `pointer` とともに `warnings` に一覧されます。
- `attack_protection` は、[攻撃防御を置き換える](../attack-protection/put.md) で書き込んだオブジェクトであり、実効値ではありません。すべてのセクションとフィールドが書き込まれます。`null` は「未設定」を意味するため、移行先の環境は独自の既定値、セキュリティ下限、プランを適用します。したがって、プロモーションによって移行元の既定値が固定されることはありません。移行先のプランに、書き込まれた設定が含まれない場合（たとえば `risk_policy.mode: enforce`）、プランの適用は `403 plan_feature_unavailable` で失敗し、何も書き込まれません。
- `role` は環境ロールです。`name`、`description`、`is_privileged`、`assignable_in_self_service`、`permissions` を持ち、各権限は `{"api": "<API key>", "value": "<permission value>"}` として記述されます（ID は環境固有のため、決して表示されません）。組み込みロール `admin` と `member` は読み取り専用です。エクスポートされず、コード `resource_skipped` と理由 `system_role` とともに `warnings` に一覧されます。ドキュメントからこれらを作成、変更、削除することはできません（`422`、`key_in_use`）。組織ロールは構成ではなくデータのため、エクスポートされません。ロールは組み込みシステム API の権限を参照できます。まだ割り当てられているロールの削除は失敗します。先に割り当てを解除してください。
- `branding` は環境の下書きテーマ、カスタム CSS、ページテンプレートです。`application_branding` はアプリケーションの下書きテーマで、テーマを持つアプリケーションにのみ表示されます。テキストの上書きと組織テーマは、まだエクスポートされません。
- 2 つのプレースホルダーの変数名が同じになる場合（キーが `-` と `_` の違いだけの場合）、両方のリソースが `warnings` に、コード `secret_ref_name_shared` とともに一覧されます。ファイル内で変数のいずれかの名前を変更してください。
- ドキュメントの JSON Schema は `https://docs.keenauth.com/config/schema/v1.json` で公開されています。補完と検証のために、エディタでこれを指定してください。

```json
{
  "apiVersion": "config.keenauth.com/v1",
  "kinds": ["connection", "api", "application"],
  "resources": [
    {"kind": "connection", "key": "db", "spec": {"type": "database", "strategy": "password", "name": "db", "display_name": null, "status": "active", "settings": {}, "client_secret": null}},
    {"kind": "api", "key": "orders", "spec": {"identifier": "https://api.example.com/orders", "name": "Orders", "access_token_lifetime_s": 3600, "token_format": "jwt", "rbac_mode": "off", "allow_offline_access": false, "require_resource_indicator": false, "dpop_required": false, "mcp_profile": false, "first_party_access": "all", "introspection_applications": [], "permissions": [{"value": "orders:read", "display_name": null, "description": null, "consent_text_i18n": {}, "sensitivity": "normal"}]}},
    {"kind": "application", "key": "web", "spec": {"name": "Web", "app_type": "spa", "default_api": "orders", "connections": ["db"], "api_grants": [{"api": "orders", "scopes": ["orders:read"], "default_scopes": []}], "redirect_uris": ["https://app.example.com/callback"]}}
  ],
  "warnings": [
    {"code": "resource_skipped", "kind": "application", "key": "partner-bot", "reason": "organization_owned"}
  ]
}
```

上記の `application` 仕様は省略しています。完全なフィールド一覧は API リファレンスを参照してください。

## エラー

| HTTP | code | 発生条件 |
|---|---|---|
| 401 | `unauthenticated` | 認証情報がないか、無効または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に必要な権限がありません。`required_permissions` に必要な権限がすべて一覧されます。 |
| 413 | `config_document_too_large` | ドキュメントが 5,000 リソースまたは 10 MiB を超えます。`kinds` で種類を絞ってエクスポートしてください。 |
| 422 | `validation_failed` | `kinds` が重複しているか、256 文字を超えているか、未知の種類を指定しています。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` 期間の後に再試行してください。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できません。`Retry-After` 期間の後に再試行してください。 |

## 例

```bash
curl "https://api.eu.keenauth.com/v1/config-export?kinds=connection,api,application" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

keenauth config export --kinds connection,api,application > keenauth.yaml
```