Organization Data Export and Import

AISIX Enterprise can export one organization as a single gzip-compressed SQL bundle and import it into another control-plane deployment running the same version. Both the dashboard and the AISIX Enterprise Admin API support export and import, on Hybrid Cloud and On-Premises alike.

This is organization-scoped, self-service portability — back up or migrate one organization's configuration and credentials without depending on a database-level snapshot. For On-Premises, it complements rather than replaces the control-plane database backup: see Backup and Restore for the Postgres-level procedure this page's import does not substitute for.

Choose a Bundle Type

Export an Organization

From the Dashboard

Open Settings → Backup & restore, choose whether to redact credentials, set the audit-trail window, and optionally include request telemetry, then select Download backup.

Redaction is off by default for organization owners. Organization admins can only export redacted bundles, so the toggle stays on and locked for them.

From the Admin API

# AISIX_CP includes /api and has no trailing slash.
export AISIX_CP="YOUR_AISIX_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"

curl -fSL "${AISIX_CP}/data_export" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -OJ

Add ?redact=true for a redacted bundle. The endpoint also takes audit_since (an RFC 3339 timestamp, default 30 days before the export), include_usage_events (false by default, whether request telemetry is included at all), and usage_since (an RFC 3339 timestamp, default 7 days before the export, with no effect unless usage events are included).

The response is application/gzip; Content-Disposition supplies a filename of the form aisix-export-<org-slug>-<UTC-timestamp>-full.sql.gz (or -redacted.sql.gz), and the X-Aisix-Export-Redacted header confirms the mode. Verify the download completed before storing or transferring it:

gzip -t aisix-export-acme-20260918T101500Z-full.sql.gz

Redacted exports are available to organization admins and owners, or to a custom role with the data_export read permission. A full export is owner-only, and an owner using an admin token needs one with the write scope — a read-only token cannot download live credentials.

Audit events and usage events are each capped at 100,000 rows per export, newest first; the bundle manifest marks a truncated table rather than failing the export. Only one export can run per organization at a time, and at most two across the deployment — a request beyond either limit gets 409 EXPORT_IN_PROGRESS. Every completed export records an audit event with its mode, parameters, master-key fingerprint, per-table row counts, and truncation state.

Import an Organization

Import applies the whole bundle in one database transaction: it either succeeds completely or changes nothing. The target must run the same control-plane version as the source, because the bundle carries data, not a schema.

Into a Populated Deployment

Sign in to the target deployment as a person — admin tokens are rejected for this operation — open Settings → Backup & restore, and use Restore from a file. The signed-in person becomes an owner of each imported organization. Import does not merge organizations or users: it refuses a bundle when an organization or user it carries already exists on the target.

Into an Empty On-Premises Deployment

For disaster recovery onto a fresh On-Premises deployment, start the services that create the schema the bundle loads into, then call the import endpoint without authentication while the deployment still holds no users or organizations:

1. Start with an empty database, then start cp-api and leave it running — it applies the database migrations and serves the import endpoint.

2. Start dp-manager. Its embedded Kine backend creates the table that receives the gateways' projected configuration.

3. Upload the bundle:

   export AISIX_CP="YOUR_AISIX_ADMIN_API_URL"
   export AISIX_BUNDLE="aisix-export-acme-20260918T101500Z-full.sql.gz"
   
   curl -fS -X POST "${AISIX_CP}/data_import" \
     -H "Content-Type: application/gzip" \
     --data-binary "@${AISIX_BUNDLE}"

This unauthenticated bootstrap path closes as soon as either a user or an organization exists on the target, so it only works for the very first import into a fresh deployment.

Finish the Import

Check the ca field in a successful import response before treating the organization as ready:

Imported accounts keep their existing passwords after a full import. After a redacted import, sign in to an imported account with the password aisix-repro, then reconnect the organization's gateways — a redacted bundle excludes the source certificate authority, so the target issues new certificates and no process restart is needed.

A migration between deployments that do not share master keys should use a redacted bundle rather than a full one; after import, replace every synthetic credential — provider credentials, caller API keys, integration credentials, account passwords — before treating the migration as complete. Either way, import resets the organization's plan and billing row to the target deployment's defaults; the bundle retains the source billing rows for reference, but they are not authoritative afterward.

What a Bundle Carries

A full bundle holds, for one organization: environments, models, credentials, routing and traffic policies, caller API keys, teams and members; the projected configuration its gateways read; audit events from the requested window; request telemetry when requested; the relevant user accounts and memberships, including password hashes; credentials still wrapped under the source deployment's master key; and the root certificate authority's private key with the gateway-certificate ledgers. Gateway certificate private keys are not included — the control plane returns one only when it issues the certificate, and does not store it.

A redacted bundle substitutes known synthetic values instead of blanking fields, which preserves resource relationships so the configuration loads without exposing live credentials — it does not restore working upstream credentials. Provider keys, MCP and A2A secrets, guardrail credentials, exporter credentials, and notification channel URLs and headers become REDACTED-<8 hex>; credential URLs become https://redacted.invalid/<8 hex>. Equal values get the same placeholder within one bundle, and a per-export salt changes the placeholders between exports. Account passwords become aisix-repro, including for accounts that previously used only social sign-in, and the certificate authority and certificate ledgers are excluded entirely. Names, email addresses, operator-authored templates and prompts, model names, and address-style URLs stay unchanged because reproducing the configuration needs them — review a redacted bundle for that content before sharing it outside the organization.

Bundle Manifest

The gzip file holds SQL data in dependency order, followed by sequence resets, and carries no schema of its own. Its opening comment includes instructions for that bundle and a machine-readable manifest:

-- AISIX-MANIFEST: {"format":"aisix-org-export/1", …}

Import Limits and Refusals

A bundle may be at most 1 GiB compressed and 8 GiB decompressed.

Avoid Direct Database Loads

The bundle contains SQL data that PostgreSQL tools can inspect, but loading it directly is not a supported restore workflow. Starting cp-api to create the schema also creates control-plane state that can conflict with rows in a full bundle, and AISIX provides no separate operator workflow for preparing a schema-only target.

Use the import endpoint for recovery instead. It validates bundle scope, applies the rows in one transaction, handles certificate-authority conflicts, re-encrypts redacted credentials, and resets billing state. A direct SQL load bypasses every one of those protections and can leave a partial restore if a later statement fails.

Rehearse a Recovery

Export a full bundle before every On-Premises control-plane upgrade — this is a companion to, not a substitute for, the database backup the upgrade guide already requires. To rehearse organization recovery on its own, deploy the current control-plane version on another host with a fresh database and the required master keys, then import the bundle: this confirms the organization can be restored before its schema changes, without needing a full database restore drill.

Next Steps

See Backup and Restore for the On-Premises database-level backup this feature complements, and Disaster Recovery for how both fit into the broader recovery picture.