#Importing and Exporting Organizations

This guide shows you how to export an organization — or one tenant of it — to a compressed file and import that file on another Enterprise Stack installation. Typical uses are moving an organization between data centers and restoring entries deleted by mistake.

#Prerequisites

Before you begin, ensure you have:

• The import-export feature enabled.
• A Bearer token for an account that holds the relevant permission on the organization or tenant you are exporting or importing.
• On the target installation, a superadmin-created organization with the same id as the source. Organization ids are not renamed. For a tenant import, that organization must already exist on the target.

#What an Export Contains

Never exported: flags such as superadmin, roles in other organizations, maintenance and ownership state (they belong to the installation), licence and usage data, and short-lived OAuth codes.

#Permissions

#Export This Organization or Tenant

Both endpoints act on the organization or tenant they are called for (/v1/{orgID}/… or /v1/{orgID}.{tenantID}/…). The response body is the compressed file.

curl -X 'GET' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/organization-management-api/export?include=audit,events' \
  -H 'accept: application/octet-stream' \
  -H 'Authorization: Bearer {yourToken}' \
  --output acme.jsonl.zst

#Import an Export File

Send the file from the export endpoint as the raw request body. Compression (zstd or gzip) is recognized from the file's magic bytes — you do not pass a compression parameter. Call it on what was exported: the same organization, or the same tenant path.

The whole file is checked before anything is written. Then nothing that exists is overwritten, so repeating an import is safe.

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/organization-management-api/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/octet-stream' \
  -H 'Authorization: Bearer {yourToken}' \
  --data-binary @acme.jsonl.zst

{
  "organization": "acme",
  "root": "acme",
  "inFile": {
    "organization": 1,
    "entries": 412,
    "hostAliases": 2,
    "accounts": 9,
    "logins": 7,
    "loginData": 7,
    "audit": 1830
  },
  "inserted": {
    "organization": 1,
    "entries": 409,
    "hostAliases": 1,
    "accounts": 8,
    "logins": 6,
    "loginData": 6,
    "audit": 1830
  },
  "skippedExisting": {
    "entries": 3,
    "hostAliases": 1,
    "accounts": 1,
    "logins": 1,
    "loginData": 1
  },
  "accountsMerged": 1,
  "warnings": []
}

🎉 You've imported an organization or tenant from an export file.

#How an Import Behaves

The whole file is checked before anything is written. An import is refused with 400, and nothing is written, if:

• The file is not a zstd or gzip compressed export, or its format version is not supported.
• It is an export of something other than what it is imported into.
• It has no closing summary, or the summary does not match its contents — it is incomplete or was altered.
• An entry lies outside what is imported into, or names a parent other than the one its path implies.
• A parent, a service dependency, or a role that an account holds is neither in the file nor already there — so a tenant export that depends on an organization-level KMS needs that KMS on the target.
• An account holds roles in another organization, or a login belongs to an account not in the file.
• A host alias is used by another organization on the target.
• The eIDAS audit chain does not verify link by link.
• An entry appears twice, or a line is not a valid record.

Nothing that exists is overwritten:

• Entries, host aliases, events, and logins that exist are left unchanged.
• An account that exists — with the same id, or for a person, the same e-mail address — keeps everything it has and only gains the file's roles; its logins are not imported, since it has its own.
• The organization's profile, billing, and configuration replace what it was created with on the target; its maintenance and ownership state are kept.
• The audit chain is restored exactly as it was — sequence numbers and hashes included, so it still verifies — and only into an organization that has no chain yet. Otherwise it is skipped.

So importing the same file twice is safe, and importing an older export restores what has been deleted since without reverting what has changed.

The upload is held in a temporary file on the API pod for the duration of the import, because it is read twice. Size the pod's temporary storage for the largest organization you expect to import.

#Moving an Organization to Another Installation

1. On the source, put the organization (or tenant) into maintenance mode so the export is a consistent snapshot. Reading keeps working meanwhile. Import is a write and is refused while that window is active.
2. Export it.
3. On the target, a superadmin creates the organization with the same id. Organization ids must be free on the target, since nothing is renamed. For a tenant, the organization must exist there already.
4. Import the file into it.
5. Move the DNS names of the organization's host aliases to the target. The URLs in credentials already issued — DIDs (did:web), issuer and status list URLs — point to those names, so they keep working only if the names move with the organization.
6. Make sure the target can reach what the export only references:
   • Status lists are published to object storage (S3, Azure, GCP), not stored in the database, and credentials already issued point to their URLs. Keep the bucket where it is and give the target access to it; nothing needs copying.
   • Keys held in an external KMS or HSM (AWS, Azure, PKCS#11).
   
   Both reach their storage through resource-access entries of the installation's configuration, which an export cannot carry. The import lists every such reference the target does not have in warnings (and logs them); add those entries to the target's resource-access configuration, or those services fail — revocation included.
7. Check the result, then end maintenance mode on the source and, when all is well, delete it there.

To merge with an organization on the target installation afterwards, offer and accept ownership there (requires the organization-ownership feature).

#File Format

JSON Lines, compressed with zstd (.jsonl.zst) or gzip (.jsonl.gz):

• Line 1: a header — {"format":"waltid-organization-export","version":2,"organization":"acme","root":"acme","exportedAt":"..."}
• Then one record per line: {"record":"entry","value":{...}}, with record one of organization, entry, host-alias, account, login, login-data, event, audit
• Last: {"record":"summary","counts":{...},"externalDependencies":[...]}, listing how many records of each kind the file holds and the services outside the export that exported services depend on.

INFO is logged when an export or import starts and finishes, with the path, the account, the counts, and the time taken. WARN is logged when an import is refused, with the problems found.

#Next Steps

• Create Organization — Recreate the organization on the target before importing.
• Host Aliases — Move DNS names so issued credential URLs keep resolving.
• Features — Enable import-export in _features.conf.