Organization Backup and Restore

An On-Premises AISIX Cloud control plane can export one organization as a gzip-compressed SQL bundle and restore it onto a freshly installed control plane running the same version. 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.

Organization export and restore are available on On-Premises only. The API7-hosted Hybrid Cloud service offers neither.

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 be freshly installed, 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. The bundle's accounts replace the target's first administrator and keep their passwords.
Redacted	Reproduce an organization for investigation, or migrate its structure without sharing the source master keys.	The target must be freshly installed and run the same control-plane version. The restore re-encrypts the synthetic credentials under the target's master key. The target's first administrator stays as the organization's owner, the restored accounts cannot sign in until it enables them, and every caller API key must be rotated before use.

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.

An export also requires that dp-manager has started at least once against this database. Its embedded Kine backend creates the table that holds the gateways' projected configuration, and that table is part of every bundle, so a deployment where dp-manager has never run receives 409 DATA_EXPORT_UNAVAILABLE. Start dp-manager once and export again. The import endpoint states the same precondition from the other side as 409 PROJECTION_TABLE_MISSING. Every completed export adds an audit event with its mode, parameters, master-key fingerprint, per-table row counts, and truncation state.

Restore an Organization

A restore loads a bundle onto a freshly installed On-Premises control plane, in place of the organization and administrator that the installation created on its first start. It does not merge into a deployment that is already in use. The restore applies the complete bundle in one database transaction, so it either succeeds in full or changes nothing.

Prepare a Fresh Target

1. Install the same control-plane version as the source, on an empty database. The bundle contains data, not the database schema, so the versions must match.
2. Configure the first administrator. For a redacted bundle, use an email address that is not in the bundle, because a redacted restore keeps this administrator.
3. For a full bundle, configure every master key needed to decrypt it. See Choose a Bundle Type.
4. Start cp-api and dp-manager. dp-manager creates the table that receives the gateways' projected configuration. Both package and Helm installations start it with the rest of the stack.
5. Sign in as the first administrator and change the initial password when the dashboard asks.

Do nothing else on the target before restoring. The restore accepts only an installation that holds exactly what its first start created: the Default organization, empty, and the first administrator as its only user. An environment, invitation, custom role, provider key, or any other organization-scoped record, another organization, or another user makes the restore fail with 409 INSTANCE_NOT_FRESH. So does an installation that was started without first-administrator settings. Install again with a new database in that case.

Upload the Bundle

Signed in as the first administrator, open Settings → Backup & restore and use Restore from a file. Only an organization owner sees the option, and only a signed-in session is accepted: admin tokens are rejected, and there is no unauthenticated restore, even into an empty database.

The bundle's organization replaces the Default organization. What happens to the people depends on the bundle type.

Finish a Full Restore

A full restore also replaces the first administrator, whose sessions end. The dashboard returns to the sign-in page: sign in with one of the bundle's accounts and its original password. Every restored account keeps its password.

The sign-in page also shows what the restore did with the certificate authority, and says when cp-api and dp-manager must be restarted. Only the replaced outcome requires a restart, because both processes load the authority at startup. The import response reports the same outcome as ca:

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 a gateway certificate under its own authority, so it kept that authority and skipped the bundle's certificate ledgers.	Register the imported organization's gateways with the target deployment again.

A target can report kept_target even though it counted as fresh: an environment that was created, had a gateway registered, and was deleted again leaves the issued certificate behind.

Finish a Redacted Restore

A redacted restore keeps the first administrator signed in, as an owner of the restored organization. The Backup & restore card shows the result, including the certificate-authority outcome, until you select Open the restored organization to switch to it. The restore loads no credential from the bundle:

• Accounts. Every restored account arrives without a password and cannot sign in, like a member created with Create user. On the Members page, enable sign-in for each person who needs dashboard access.
• Caller API keys. Each key keeps its name, models, rate limits, bindings, expiry, and disabled state, but has no usable secret. Rotate each key before clients use it; the rotation returns a working value.
• Other credentials. Provider keys, MCP and A2A secrets, guardrail and exporter credentials, and notification channel URLs are synthetic placeholders. Replace them before the organization serves production traffic.

The target uses its own certificate authority because a redacted bundle excludes the source authority and certificate ledgers, so the outcome is always unchanged. Register the imported organization's gateways with the target deployment so they receive new certificates. No process restart is required after a redacted restore.

A redacted bundle that contains the first administrator's own email address is refused with 409 USER_EXISTS. Install the target again with a first-administrator email address that is not in the bundle.

Complete a Migration

A full bundle preserves live credentials only when the target holds all master keys needed to decrypt it. After the restore, follow the certificate-authority action that the sign-in page shows and the response returns in ca.

When the deployments do not share those keys, use a redacted bundle. After the restore, enable sign-in for the accounts, rotate the caller API keys, and replace every other synthetic credential. Then register the organization's gateways with the target deployment. Treat this as configuration migration rather than live credential transfer.

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.
• Caller API key hashes become the SHA-256 hash of aisix-repro-<api_key_id>, and account passwords become aisix-repro. Because anyone who knows the IDs could derive these values, the supported restore does not load them: it gives every caller API key a random hash that no plaintext matches, and restores every account without a password. See Finish a Redacted Restore.
• OAuth tokens left from social sign-in 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	INSTANCE_NOT_FRESH	The target holds more than its first start created, or was started without first-administrator settings. See Prepare a Fresh Target.
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 redacted bundle contains the email address of the first administrator performing the restore.
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, or does not contain exactly one organization.
403	FORBIDDEN	The signed-in user is not an organization owner.
403	PASSWORD_CHANGE_REQUIRED	The first administrator has not changed the initial password yet.
401	NOT_AUTHENTICATED, INVALID_TOKEN	The request has no signed-in session, or uses an admin token or an expired session.

A successful restore returns the organization, row counts, bundle mode, and certificate-authority outcome. The warnings array is kept for compatibility and is always empty; read ca for the certificate-authority outcome:

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

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 restore in the dashboard for recovery. It validates bundle scope, applies the rows in one transaction, handles certificate-authority conflicts, and re-encrypts redacted credentials. 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, install the current control-plane version on another host with a fresh database and the required master keys, sign in as its first administrator, then restore 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, install the previous control-plane version against a fresh database with the required master keys, sign in as its first administrator, then restore the pre-upgrade bundle. The organization bundle is portable to another host, while the database backup protects the complete deployment.