# Esporta la configurazione

`GET /v1/config-export` · autorizzazione `config:read` e l'autorizzazione di lettura di ogni tipo esportato

Restituisce la configurazione dell'ambiente come un unico documento indipendente dall'ambiente, così puoi rivederla, conservarla nel controllo di versione o applicarla in seguito a un altro ambiente. Il documento non contiene id, versioni, timestamp o segreti specifici dell'ambiente: le risorse si riferiscono l'una all'altra tramite `key`. La stessa configurazione produce sempre un documento identico byte per byte (tipi nell'ordine seguente, poi per `key`; le liste di tipo insieme vengono ordinate). La risposta è JSON, che è anche YAML valido; `keenauth config export` stampa YAML per impostazione predefinita.

## Richiesta

L'ambiente deriva dalla credenziale. L'unico parametro di query è facoltativo.

| Parametro | Descrizione |
|---|---|
| `kinds` | Tipi da esportare separati da virgola, per esempio `kinds=connection,api`. Senza questo parametro vengono esportati tutti i tipi. |

| Tipo | `key` | Autorizzazioni oltre a `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` | connessione `key` | `connections:read` |
| `api` | API `key` | `apis:read`, `applications:read` |
| `role` | ruolo `key` | `roles:read`, `apis:read` |
| `application` | applicazione `key` | `applications:read`, `apis:read`, `connections:read` |
| `application_branding` | applicazione `key` | `branding:read`, `applications:read` |

`api`, `role` e `application` richiedono anche le autorizzazioni dei tipi a cui fanno riferimento, perché i riferimenti vengono risolti in `key`. `config:read` da solo non concede la lettura di alcuna risorsa.

## Risposta

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

- I riferimenti usano i valori `key`: `application.default_api`, `application.connections` (l'ordine dei pulsanti viene mantenuto), `application.api_grants[].api` e `api.introspection_applications`.
- Una connessione OIDC enterprise include il proprio materiale di federazione come `oidc` (`issuer`, `client_id`, `client_auth_method`, `provider_profile`); il redirect URI, l'host SP e il segreto stesso sono specifici dell'ambiente e non vengono esportati, e `oidc` è `null` quando il materiale non è ancora stato scritto. In un documento che applichi, `oidc: null` lascia invariato il materiale. Il tenant id di Entra non è leggibile, quindi una connessione con il profilo `entra` non può ancora essere gestita tramite il documento.
- I valori dei segreti non vengono mai esportati. Un segreto che hai fornito a KeenAuth (il `client_secret` di una connessione social o OIDC enterprise) compare come segnaposto, `{"secret_ref": {"source": "env", "name": "KEENAUTH_CONNECTION_<KEY>_CLIENT_SECRET"}}`; la CLI legge il valore da quella variabile d'ambiente quando il documento viene applicato. Le altre connessioni hanno `"client_secret": null`. I segreti emessi da KeenAuth (segreti client delle applicazioni, chiavi API, segreti di firma dei webhook) e le chiavi private non vengono esportati affatto; l'ambiente di destinazione ne emette di propri. `jwks` contiene solo chiavi pubbliche.
- L'API di sistema integrata non viene esportata; esiste in ogni ambiente. Anche le applicazioni di proprietà dell'organizzazione e le applicazioni registrate dal client stesso (Dynamic Client Registration, Client ID Metadata Document) non vengono esportate; ciascuna è elencata in `warnings` con il codice `resource_skipped`.
- Un riferimento che non può essere risolto (per esempio a un'applicazione saltata) viene rimosso dal documento ed elencato in `warnings` con il codice `reference_dropped` e un `pointer` JSON.
- `attack_protection` è l'oggetto che hai scritto con [Sostituisci protezione dagli attacchi](../attack-protection/put.md), non i valori effettivi. Ogni sezione e ogni campo viene scritto; `null` significa non impostato, quindi l'ambiente di destinazione applica i propri valori predefiniti, i minimi di sicurezza e il proprio piano. Una promozione quindi non fissa mai i valori predefiniti della sorgente. Quando il piano dell'ambiente di destinazione non include un'impostazione scritta (per esempio `risk_policy.mode: enforce`), l'applicazione del piano fallisce con `403 plan_feature_unavailable` e non viene scritto nulla.
- `role` è un ruolo di ambiente: `name`, `description`, `is_privileged`, `assignable_in_self_service` e `permissions`, con ogni autorizzazione scritta come `{"api": "<API key>", "value": "<permission value>"}` (gli id sono specifici dell'ambiente, quindi non compaiono mai). I ruoli integrati `admin` e `member` sono in sola lettura: non vengono esportati ed sono elencati in `warnings` con il codice `resource_skipped` e il motivo `system_role`; un documento non può crearli, modificarli o eliminarli (`422`, `key_in_use`). I ruoli dell'organizzazione sono dati, non configurazione, e non vengono esportati. Un ruolo può fare riferimento alle autorizzazioni dell'API di sistema integrata. Eliminare un ruolo ancora assegnato fallisce; prima rimuovi l'assegnazione.
- `branding` è il tema in bozza dell'ambiente, il CSS personalizzato e il template della pagina; `application_branding` è il tema in bozza di un'applicazione e compare solo per le applicazioni che ne hanno uno. Le sostituzioni dei testi e i temi dell'organizzazione non vengono ancora esportati.
- Se due segnaposto finiscono con lo stesso nome di variabile (chiavi che differiscono solo per `-` e `_`), entrambe le risorse sono elencate in `warnings` con il codice `secret_ref_name_shared`; rinomina una delle variabili nel tuo file.
- Lo JSON Schema del documento è pubblicato in `https://docs.keenauth.com/config/schema/v1.json`; puntaci l'editor per il completamento e la validazione.

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

La specifica `application` sopra è abbreviata; l'elenco completo dei campi è nella documentazione dell'API.

## Errori

| HTTP | code | Quando |
|---|---|---|
| 401 | `unauthenticated` | La credenziale manca, non è valida o è stata revocata. |
| 403 | `insufficient_permissions` | La credenziale non ha un'autorizzazione richiesta; `required_permissions` le elenca tutte. |
| 413 | `config_document_too_large` | Il documento supererebbe 5.000 risorse o 10 MiB; esporta meno tipi con `kinds`. |
| 422 | `validation_failed` | `kinds` è ripetuto, supera i 256 caratteri o indica un tipo sconosciuto. |
| 429 | `rate_limited` | È stato superato il limite di richieste; riprova dopo il periodo `Retry-After`. |
| 503 | `service_unavailable` | Una dipendenza è temporaneamente non disponibile; riprova dopo il periodo `Retry-After`. |

## Esempio

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