# Export configuration

Call `POST /v1/exports` with `exports:write` to export the current environment, or include `organization` for one organization. HTTP 202 returns `pending`. Poll `GET /v1/exports/{export}`; both [management API](/reference/api/management/) operations require `exports:write`. Dashboard-session callers also need a recent second factor.

A ready export uses `ohauthcat.import_bundle` version 1, `source: generic`. It carries supported organizations, connection configuration including IdP metadata/certificates, directories, users, groups, memberships and profiles. Current object IDs become legacy IDs for a later import. This is configuration portability, not a database backup.

## Secrets and download limits

The bundle never reads or includes OIDC client secrets, SCIM token hashes or SP private keys. `secrets_to_reenter` names the object and kind. Re-enter secrets securely when importing elsewhere; tokens and private keys cannot be recovered from the export.

Inspect `state`, `failure_reason` and every item in `bundles`. A whole-environment export that exceeds a bundle limit is split into one independently importable bundle per organization. A single-bundle export retains top-level `download_url` and `expires_at`; a split export omits those top-level fields and supplies download information on its ready bundle items.

Each bundle reports `organization`, `state`, `size` in bytes and, when applicable, `failure_reason`. An organization that cannot fit on its own or disappears during processing has a failed bundle while other bundles can remain ready. The export is ready when at least one bundle succeeds; it fails when all bundles fail. A ready export therefore does not mean every organization was exported. An empty environment still fails. If the environment exceeds the supported split size, request exports for individual organizations.

## Processing and download expiry

With object storage configured, the worker processes pending exports and stores a private JSON bundle encrypted with the configured KMS key. The API and worker must share the export storage configuration. This is implemented behavior, not evidence that a hosted bucket or worker has been deployed. Without a configured sink, an export stays pending; the local sink writes a file.

For object storage, each successful read signs each ready bundle's `download_url` afresh. Its lifetime is at most 15 minutes and never extends beyond the export's 24-hour bundle retention after completion. Each `expires_at` describes that URL's expiry. Read the export again for fresh URLs while the bundles remain valid; reading does not extend retention. Failed bundles have no download URL.

The worker retries a transient failure once, then marks the export failed. Storage or database failures retry the whole export. Nothing to export, a missing requested organization or no organization fitting in a bundle can fail immediately. Start a new export after resolving a failure.

Protect the bundle as sensitive tenant data even though secrets are excluded. A pending response does not prove a downloadable hosted export exists.
