# Konfiguration exportieren

`GET /v1/config-export` · Berechtigung `config:read` und die Leseberechtigung jeder exportierten Art

Gibt die Konfiguration der Umgebung als ein umgebungsunabhängiges Dokument zurück, damit Sie sie prüfen, in der Versionsverwaltung ablegen oder später auf eine andere Umgebung anwenden können. Das Dokument enthält keine umgebungsspezifischen IDs, Versionen, Zeitstempel oder Geheimnisse: Ressourcen verweisen aufeinander über `key`. Dieselbe Konfiguration erzeugt stets ein byteidentisches Dokument (Arten in der unten genannten Reihenfolge, dann nach `key`; mengenartige Listen sortiert). Die Antwort ist JSON, das zugleich gültiges YAML ist; `keenauth config export` gibt standardmäßig YAML aus.

## Anfrage

Die Umgebung ergibt sich aus den Anmeldedaten. Der einzige Abfrageparameter ist optional.

| Parameter | Beschreibung |
|---|---|
| `kinds` | Durch Kommas getrennte Arten zum Export, zum Beispiel `kinds=connection,api`. Ohne diesen Parameter wird jede Art exportiert. |

| Art | `key` | Berechtigungen neben `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` | Verbindung `key` | `connections:read` |
| `api` | API `key` | `apis:read`, `applications:read` |
| `role` | Rolle `key` | `roles:read`, `apis:read` |
| `application` | Anwendung `key` | `applications:read`, `apis:read`, `connections:read` |
| `application_branding` | Anwendung `key` | `branding:read`, `applications:read` |

`api`, `role` und `application` benötigen außerdem die Berechtigungen der Arten, auf die sie verweisen, weil Verweise zu `key`-Werten aufgelöst werden. `config:read` allein gewährt kein Lesen von Ressourcen.

## Antwort

`200 OK` mit `Cache-Control: no-store`.

- Verweise verwenden `key`-Werte: `application.default_api`, `application.connections` (die Reihenfolge der Schaltflächen bleibt erhalten), `application.api_grants[].api` und `api.introspection_applications`.
- Eine Enterprise-OIDC-Verbindung führt ihr Föderationsmaterial als `oidc` (`issuer`, `client_id`, `client_auth_method`, `provider_profile`); die Redirect-URI, der SP-Host und das Geheimnis selbst sind umgebungsspezifisch und werden nicht exportiert, und `oidc` ist `null`, wenn noch kein Material geschrieben wurde. In einem Dokument, das Sie anwenden, lässt `oidc: null` das Material unverändert. Die Entra-Mandanten-ID ist nicht lesbar, daher kann eine Verbindung mit dem `entra`-Profil über das Dokument noch nicht verwaltet werden.
- Geheimniswerte werden nie exportiert. Ein Geheimnis, das Sie KeenAuth übergeben haben (das `client_secret` einer Social- oder Enterprise-OIDC-Verbindung), erscheint als Platzhalter `{"secret_ref": {"source": "env", "name": "KEENAUTH_CONNECTION_<KEY>_CLIENT_SECRET"}}`; die CLI liest den Wert beim Anwenden des Dokuments aus dieser Umgebungsvariablen. Andere Verbindungen haben `"client_secret": null`. Von KeenAuth ausgestellte Geheimnisse (Client-Secrets von Anwendungen, API-Schlüssel, Webhook-Signaturgeheimnisse) und private Schlüssel werden überhaupt nicht exportiert; die Zielumgebung stellt eigene aus. `jwks` enthält nur öffentliche Schlüssel.
- Die integrierte System-API wird nicht exportiert; sie existiert in jeder Umgebung. Organisationseigene Anwendungen sowie Anwendungen, die der Client selbst registriert (Dynamic Client Registration, Client ID Metadata Document), werden ebenfalls nicht exportiert; jede davon ist in `warnings` mit dem Code `resource_skipped` aufgeführt.
- Ein Verweis, der nicht aufgelöst werden kann (zum Beispiel auf eine übersprungene Anwendung), wird aus dem Dokument entfernt und in `warnings` mit dem Code `reference_dropped` und einem JSON-`pointer` aufgeführt.
- `attack_protection` ist das Objekt, das Sie mit [Attack Protection ersetzen](../attack-protection/put.md) geschrieben haben, nicht die wirksamen Werte. Jeder Abschnitt und jedes Feld wird geschrieben; `null` bedeutet nicht gesetzt, sodass die Zielumgebung ihre eigenen Standardwerte, Sicherheitsuntergrenzen und ihren Tarif anwendet. Eine Übernahme fixiert daher nie die Standardwerte der Quelle. Wenn der Tarif der Zielumgebung eine geschriebene Einstellung nicht enthält (zum Beispiel `risk_policy.mode: enforce`), schlägt das Anwenden des Plans mit `403 plan_feature_unavailable` fehl, und es wird nichts geschrieben.
- `role` ist eine Umgebungsrolle: `name`, `description`, `is_privileged`, `assignable_in_self_service` und `permissions`, wobei jede Berechtigung als `{"api": "<API key>", "value": "<permission value>"}` geschrieben wird (IDs sind umgebungsspezifisch und erscheinen daher nie). Die integrierten Rollen `admin` und `member` sind schreibgeschützt: Sie werden nicht exportiert und in `warnings` mit dem Code `resource_skipped` und dem Grund `system_role` aufgeführt; ein Dokument kann sie nicht anlegen, ändern oder löschen (`422`, `key_in_use`). Organisationsrollen sind Daten, keine Konfiguration, und werden nicht exportiert. Eine Rolle kann auf Berechtigungen der integrierten System-API verweisen. Eine Rolle, die noch zugewiesen ist, lässt sich nicht löschen; entfernen Sie die Zuweisung zuerst.
- `branding` ist der Theme-Entwurf der Umgebung, das benutzerdefinierte CSS und die Seitenvorlage; `application_branding` ist der Theme-Entwurf einer Anwendung und erscheint nur bei Anwendungen, die einen besitzen. Textersetzungen und Organisations-Themes werden noch nicht exportiert.
- Wenn zwei Platzhalter am Ende denselben Variablennamen haben (Schlüssel, die sich nur in `-` und `_` unterscheiden), werden beide Ressourcen in `warnings` mit dem Code `secret_ref_name_shared` aufgeführt; benennen Sie in Ihrer Datei eine der Variablen um.
- Das JSON-Schema des Dokuments wird unter `https://docs.keenauth.com/config/schema/v1.json` veröffentlicht; verweisen Sie Ihren Editor darauf, um Vervollständigung und Validierung zu erhalten.

```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"}
  ]
}
```

Die Spezifikation `application` oben ist gekürzt; die vollständige Feldliste steht in der API-Referenz.

## Fehler

| HTTP | Code | Wann |
|---|---|---|
| 401 | `unauthenticated` | Die Anmeldedaten fehlen, sind ungültig oder wurden widerrufen. |
| 403 | `insufficient_permissions` | Den Anmeldedaten fehlt eine erforderliche Berechtigung; `required_permissions` listet alle auf. |
| 413 | `config_document_too_large` | Das Dokument würde 5.000 Ressourcen oder 10 MiB überschreiten; exportieren Sie weniger Arten mit `kinds`. |
| 422 | `validation_failed` | `kinds` ist mehrfach angegeben, länger als 256 Zeichen oder nennt eine unbekannte Art. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach dem Zeitraum `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach dem Zeitraum `Retry-After`. |

## Beispiel

```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
```