# Exportar la configuración

`GET /v1/config-export` · permiso `config:read` y el permiso de lectura de cada tipo exportado

Devuelve la configuración del entorno como un único documento independiente del entorno, para que pueda revisarla, conservarla en control de versiones o aplicarla más adelante a otro entorno. El documento no contiene ids, versiones, marcas de tiempo ni secretos específicos del entorno: los recursos se referencian entre sí mediante `key`. La misma configuración siempre produce un documento idéntico byte a byte (tipos en el orden indicado abajo y, dentro de cada tipo, por `key`; las listas de tipo conjunto se ordenan). La respuesta es JSON, que también es YAML válido; `keenauth config export` imprime YAML por defecto.

## Solicitud

El entorno se obtiene de la credencial. El único parámetro de consulta es opcional.

| Parámetro | Descripción |
|---|---|
| `kinds` | Tipos separados por comas que se exportarán, por ejemplo `kinds=connection,api`. Si se omite, se exportan todos los tipos. |

| Tipo | `key` | Permisos además de `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` | conexión `key` | `connections:read` |
| `api` | API `key` | `apis:read`, `applications:read` |
| `role` | rol `key` | `roles:read`, `apis:read` |
| `application` | aplicación `key` | `applications:read`, `apis:read`, `connections:read` |
| `application_branding` | aplicación `key` | `branding:read`, `applications:read` |

`api`, `role` y `application` también necesitan los permisos de los tipos a los que referencian, porque las referencias se resuelven a `key`s. `config:read` por sí solo no concede lectura de ningún recurso.

## Respuesta

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

- Las referencias usan `key`s: `application.default_api`, `application.connections` (se mantiene el orden de los botones), `application.api_grants[].api` y `api.introspection_applications`.
- Una conexión OIDC empresarial incluye su material de federación como `oidc` (`issuer`, `client_id`, `client_auth_method`, `provider_profile`); la URI de redirección, el host de SP y el propio secreto son específicos del entorno y no se exportan, y `oidc` es `null` cuando todavía no se ha escrito material. En un documento que aplique, `oidc: null` deja el material sin cambios. El id de inquilino de Entra no es legible, por lo que una conexión con el perfil `entra` no puede gestionarse todavía mediante el documento.
- Los valores secretos nunca se exportan. Un secreto que usted proporcionó a KeenAuth (el `client_secret` de una conexión social o OIDC empresarial) aparece como un marcador, `{"secret_ref": {"source": "env", "name": "KEENAUTH_CONNECTION_<KEY>_CLIENT_SECRET"}}`; la CLI lee el valor de esa variable de entorno al aplicar el documento. Las demás conexiones tienen `"client_secret": null`. Los secretos que emite KeenAuth (secretos de cliente de aplicaciones, claves de API, secretos de firma de webhooks) y las claves privadas no se exportan en absoluto; el entorno de destino emite los suyos. `jwks` contiene solo claves públicas.
- La API del sistema integrada no se exporta; existe en todos los entornos. Las aplicaciones propiedad de la organización y las aplicaciones registradas por el propio cliente (Dynamic Client Registration, Client ID Metadata Document) tampoco se exportan; cada una aparece en `warnings` con el código `resource_skipped`.
- Una referencia que no puede resolverse (por ejemplo, a una aplicación omitida) se elimina del documento y se incluye en `warnings` con el código `reference_dropped` y un `pointer` en JSON.
- `attack_protection` es el objeto que escribió con [Reemplazar protección contra ataques](../attack-protection/put.md), no los valores efectivos. Se escriben todas las secciones y campos; `null` significa no definido, de modo que el entorno de destino aplica sus propios valores predeterminados, mínimos de seguridad y plan. Por tanto, una promoción nunca fija los valores predeterminados del origen. Cuando el plan del destino no incluye un ajuste escrito (por ejemplo `risk_policy.mode: enforce`), la aplicación del plan falla con `403 plan_feature_unavailable` y no se escribe nada.
- `role` es un rol del entorno: `name`, `description`, `is_privileged`, `assignable_in_self_service` y `permissions`, cada permiso escrito como `{"api": "<API key>", "value": "<permission value>"}` (los ids son específicos del entorno, por lo que nunca aparecen). Los roles integrados `admin` y `member` son de solo lectura: no se exportan y se listan en `warnings` con el código `resource_skipped` y el motivo `system_role`; un documento no puede crearlos, cambiarlos ni eliminarlos (`422`, `key_in_use`). Los roles de organización son datos, no configuración, y no se exportan. Un rol puede referirse a los permisos de la API del sistema integrada. Eliminar un rol que aún está asignado falla; quítelo de las asignaciones primero.
- `branding` es el tema borrador, el CSS personalizado y la plantilla de página del entorno; `application_branding` es el tema borrador de una aplicación y solo aparece en las aplicaciones que tienen uno. Los reemplazos de texto y los temas de organización todavía no se exportan.
- Si dos marcadores terminan con el mismo nombre de variable (claves que solo difieren en `-` y `_`), ambos recursos se listan en `warnings` con el código `secret_ref_name_shared`; renombre una de las variables en su archivo.
- El JSON Schema del documento se publica en `https://docs.keenauth.com/config/schema/v1.json`; apunte su editor a él para autocompletado y validación.

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

El spec `application` anterior está abreviado; la lista completa de campos está en la referencia de la API.

## Errores

| HTTP | código | Cuándo |
|---|---|---|
| 401 | `unauthenticated` | Falta la credencial, no es válida o fue revocada. |
| 403 | `insufficient_permissions` | La credencial no tiene un permiso requerido; `required_permissions` enumera todos ellos. |
| 413 | `config_document_too_large` | El documento superaría 5.000 recursos o 10 MiB; exporte menos tipos con `kinds`. |
| 422 | `validation_failed` | `kinds` está repetido, tiene más de 256 caracteres o nombra un tipo desconocido. |
| 429 | `rate_limited` | Se superó el límite de solicitudes; reintente después del período `Retry-After`. |
| 503 | `service_unavailable` | Una dependencia no está disponible temporalmente; reintente después del período `Retry-After`. |

## Ejemplo

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