Skip to content
Dashboard
Theme
Theme

Export configuration

Create a portable ImportBundle and inspect its state and omitted secrets.

View Markdown

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

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.

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.