Organization Backup and Restore

AISIX Cloud can export one organization as a gzip-compressed SQL bundle and import it into another control-plane deployment running the same version. The dashboard and Admin API workflows are available with both Hybrid Cloud and On-Premises. A full bundle retains credentials and certificate state for backup or migration between deployments that share the required master keys. A redacted bundle replaces credentials with synthetic values for support reproduction or migration without sharing the source keys.

Choose a Bundle Type

Choose the bundle type according to whether the target can safely use the source deployment's master keys:

Bundle	Use it to	Restore requirements
Full	Back up an organization or migrate it without replacing its credentials.	The target must run the same control-plane version and hold every source master key needed to decrypt the bundle, including a retired key that still wraps a stored value.
Redacted	Reproduce an organization for investigation, or migrate its structure without sharing the source master keys.	The target must run the same control-plane version. The import re-encrypts the synthetic credentials under the target's master key. Replace the synthetic credentials before using the imported organization for production traffic.

Protect full bundles as database backups

A full bundle contains live credentials. Credentials remain envelope-encrypted in the configuration tables, but the projected gateway documents contain their plaintext values. The bundle also carries the root certificate authority's private key. Store and transfer it with the same controls as the database.

Export an Organization

Use the dashboard for an interactive export, or use the Admin API to automate scheduled backups and support-bundle generation.

Use the Dashboard

Open Settings → Backup & restore. Choose whether to redact credentials, set the audit-trail window, and optionally include request telemetry. Select Download backup to export the bundle.

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

Use the Admin API

Set the Admin API base URL and an admin token before exporting:

# AISIX_CP includes /api and has no trailing slash.
# The local On-Premises quickstart uses http://localhost:8080/api.
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"

The following request downloads a full bundle and uses the server-provided filename:

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

Add ?redact=true to download a redacted bundle. The endpoint also accepts these parameters:

Parameter	Default	Effect
redact	false	Replaces credentials with synthetic values.
audit_since	30 days before the export	Sets the audit-event lower bound as an RFC 3339 timestamp.
include_usage_events	false	Includes request telemetry.
usage_since	7 days before the export	Sets the usage-event lower bound as an RFC 3339 timestamp. It has no effect unless usage events are included.

The response is application/gzip. Its Content-Disposition header supplies one of these filenames:

aisix-export-<org-slug>-<UTC YYYYMMDDThhmmssZ>-full.sql.gz
aisix-export-<org-slug>-<UTC YYYYMMDDThhmmssZ>-redacted.sql.gz

The X-Aisix-Export-Redacted response header also identifies the mode as true or false.

Confirm that the download is complete before storing or transferring it:

export AISIX_BUNDLE="PATH_TO_DOWNLOADED_BUNDLE"
gzip -t "${AISIX_BUNDLE}"

Redacted exports are available to organization admins and owners. A custom role can also download one when it has the data-export read permission. A full export is owner-only. When an owner uses an admin token, that token must have the write scope; a read-only token cannot download live credentials.

Audit events and usage events are each capped at 100,000 rows, newest first. Reaching a cap does not fail the export. The bundle manifest marks the affected table as truncated.

Only one export can run for an organization at a time, with at most two exports across the deployment. A request beyond either limit receives 409 EXPORT_IN_PROGRESS. Every completed export adds an audit event with its mode, parameters, master-key fingerprint, per-table row counts, and truncation state.

Restore an Organization

The supported import route applies the complete bundle in one database transaction. The import either succeeds in full or changes nothing. The target must run the same control-plane version as the source because the bundle contains data, not the database schema.

Choose the procedure that matches the target state:

• For a deployment that already contains a user or organization, sign in to the dashboard and upload the bundle. This path is available with both Hybrid Cloud and On-Premises.
• For disaster recovery into an empty On-Premises deployment, start the required services and call the import endpoint without authentication.

Restore to a Populated Deployment

Sign in to the target deployment as a person, then open Settings → Backup & restore and use Restore from a file. Admin tokens are rejected for this operation. The signed-in person becomes an owner of each imported organization.

The import does not merge organizations or users. It refuses a bundle when an organization or user in that bundle already exists on the target.

Restore to an Empty On-Premises Deployment

The first two services create the database structures that receive the bundle. Start them before importing:

1. Start with an empty database.

2. Start cp-api and leave it running. It applies the database migrations and serves the import endpoint.

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

4. Set the Admin API base URL for the new deployment and the bundle path:

   # AISIX_CP includes /api and has no trailing slash.
   export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
   export AISIX_BUNDLE="aisix-export-acme-20260916T101500Z-full.sql.gz"

5. Upload the bundle. Do not send credentials: the bootstrap import is available only while the control plane contains no users and no organizations.

   curl -fS -X POST "${AISIX_CP}/data_import" \
     -H "Content-Type: application/gzip" \
     --data-binary "@${AISIX_BUNDLE}"

As soon as either a user or an organization exists, the unauthenticated bootstrap path closes.

Complete a Migration

A full bundle preserves live credentials only when the target holds all master keys needed to decrypt it. After import, follow the certificate-authority action returned in ca.

When the deployments do not share those keys, use a redacted bundle. After import, replace every synthetic credential, including provider credentials, caller API keys, integration credentials, and account passwords. Then register the organization's gateways with the target deployment. Treat this as configuration migration rather than live credential transfer.

Finish a Full Restore

Check the ca value in the successful import response:

ca value	Certificate-authority outcome	Required action
replaced	The bundle's certificate authority replaced the unused authority on the target.	Restart cp-api and dp-manager. Both processes load the authority at startup. The restored gateways can then continue using their existing certificates.
unchanged	The bundle carried the same authority or no authority.	No certificate-related action is required.
kept_target	The target had already issued certificates under a different authority, so it kept its own authority and skipped the bundle's certificate ledgers.	Register the imported organization's gateways with the target deployment again. Review warnings for the skipped certificate state.

The imported accounts retain their existing passwords.

Finish a Redacted Restore

Sign in to an imported account with the password aisix-repro. The target uses its own certificate authority because a redacted bundle excludes the source authority and certificate ledgers. Register the imported organization's gateways with the target deployment so they receive new certificates.

No process restart is required after a redacted import.

Review the Billing Reset

An import resets the organization's plan and billing row to the defaults of the target deployment. This applies to full and redacted bundles, whether the target was empty or populated. The bundle retains the source billing rows for investigation, but they are not authoritative after import.

Understand Bundle Contents

A full bundle includes the following data for one organization:

• environments, models, credentials, routing and traffic policies, API keys, teams, and members;
• the projected configuration read by the organization's gateways;
• audit events from the requested window;
• request telemetry when requested;
• relevant user accounts and memberships, including password hashes;
• credentials still wrapped under the source deployment's master key;
• the root certificate authority private key and gateway-certificate ledgers.

Gateway certificate private keys are not included because the control plane returns each private key only when it issues the certificate and does not store it.

Redacted Credentials

A redacted bundle substitutes known synthetic values rather than empty strings. This preserves resource relationships and allows the restored configuration to load without exposing live credentials. It does not restore working credentials for upstream providers or other external services.

• Provider keys, MCP and A2A secrets, guardrail credentials, observability-exporter credentials, notification channel URLs and headers, and other stored tokens become REDACTED-<8 hex>. Credential URLs become https://redacted.invalid/<8 hex>.
• Equal values receive the same placeholder within one bundle, while different values remain distinct. A per-export salt makes the placeholders change between exports.
• The database row and projected gateway document store the SHA-256 hash of aisix-repro-<api_key_id>, so that derived value authenticates.
• Account passwords become aisix-repro. Accounts that previously used only social sign-in also receive this synthetic password; OAuth tokens are cleared.
• The certificate authority and certificate ledgers are excluded.

Names, email addresses, operator-authored templates and prompts, model names, and address-style URLs remain unchanged because they are needed to reproduce the configuration. Review this information before sharing a redacted bundle outside the organization.

Encrypted columns in a redacted bundle are wrapped with this published reproduction key:

AISIX_CLOUD_MASTER_KEY=raNM05F3jUZE7D8C4aUZVhMFZOUSZ0wk6wkpJmgnQwE=

Its fingerprint is 230c4f58143b002f. The supported import route re-encrypts these columns under the target's master key, so the target does not need this key. Never configure a production deployment with the reproduction key; the control plane logs a warning when it detects that configuration at startup.

Bundle Manifest

The gzip file contains SQL data in dependency order, followed by sequence resets, and does not contain a schema. Its opening comment includes instructions for that bundle and a machine-readable manifest:

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

Field	Meaning
format	Bundle contract version, currently aisix-org-export/1.
cp_version	Control-plane build that produced the bundle.
migration_version	Digest of the base-table column layout in the control-plane schema and the migration identifiers carried by the producing build. The import requires an exact match.
generated_at	Export time as an RFC 3339 timestamp.
org_id, org_slug	Exported organization.
redacted	Whether the bundle contains synthetic credentials.
ciphertext_key	Whether encrypted columns use the deployment or reproduction key.
master_key_fingerprint	Fingerprint of the source deployment's active key, or of the published reproduction key for a redacted bundle.
redaction_rules_version	Redaction ruleset used for the export.
tables	Row count, truncation state, and time window for each table.

Import Limits and Refusals

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

Status	Code	Cause
409	MIGRATION_VERSION_MISMATCH	The target schema identity differs from the bundle, usually because the control-plane versions differ.
409	ORG_EXISTS	An organization in the bundle already exists on the target.
409	USER_EXISTS	A user in the bundle already exists on the target.
409	OUT_OF_SCOPE_ROWS	The bundle contains rows outside its declared organizations. The transaction is rolled back.
409	PROJECTION_TABLE_MISSING	dp-manager has not created the projection table. Start it before importing.
409	MASTER_KEY_MISMATCH	The target does not hold the key that wraps the bundle's encrypted values.
409	MASTER_KEY_UNAVAILABLE	The target started without a master key.
400	INVALID_BUNDLE	The file is not a valid AISIX organization bundle.
403	FORBIDDEN	The target is not empty and the request does not use a signed-in user session.
401	INVALID_TOKEN	Supplied credentials are invalid or expired.

A successful import returns the organizations, row counts, bundle mode, certificate-authority outcome, warnings, and the new owner's ID when a signed-in person performed the import:

{
  "imported": [
    {
      "id": "…",
      "slug": "acme"
    }
  ],
  "redacted": false,
  "rows": {
    "models": 42
  },
  "ca": "unchanged",
  "warnings": [],
  "owner_user_id": "…"
}

Avoid Direct Database Loads

The bundle contains SQL data that PostgreSQL tools can inspect, but direct database loading 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. AISIX does not provide a separate operator workflow for preparing a schema-only target.

Use the import endpoint for recovery. 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 these protections and can leave a partial restore if a later statement fails.

Rehearse an On-Premises Upgrade

Before upgrading an On-Premises control plane, export a full bundle. To rehearse organization recovery, deploy the current control-plane version on another host with a fresh database and the required master keys, then import the bundle. This confirms that the organization can be restored before its schema changes.

If an upgrade fails, restore the complete deployment from the database backup required by Upgrade AISIX. To recover only the exported organization instead, deploy the previous control-plane version against a fresh database with the required master keys, then import the pre-upgrade bundle. The organization bundle is portable to another host, while the database backup protects the complete deployment.