Create and Restore Backups

This article explains how to back up, restore, and migrate an entire GoodData organization using the declarative API.

While restoring an organization within the same environment can be done using a simple GET and PUT workflow, migrating an organization to a different hostname or environment requires manual changes to the exported JSON layout.

The examples in this article are not meant to be used without modification. Always review and adjust the exported files to match the requirements of your target environment.

For migrating or cloning individual workspaces, see Workspace Declarative API Interface.

Retrieve Organization Layout

The following example exports the full declarative layout of the organization specified by the hostname and stores it in a JSON file named organization-layout.json.

curl -H "Authorization: Bearer $API_TOKEN" \
  -X GET \
  $HOST_URL/api/v1/layout/organization > organization-layout.json

The exported layout includes all organization-level entities such as workspaces, data source definitions, and identity provider configuration. Secrets and credentials are not included.

Restore or Modify Layout

Organization Restore Is Destructive

PUT requests to /api/v1/layout/organization fully replace the configuration of the target organization.

Before restoring or migrating an organization:

  1. Create a backup of the target organization
  2. Verify that you are using the correct API token and hostname
  3. Ensure all required secrets and credentials are available

The following example restores an organization using a previously exported declarative layout:

curl -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -X PUT \
  $HOST_URL/api/v1/layout/organization \
  -d @organization-layout.json

Missing Credentials in Reimported Data Sources

Secrets are not included in declarative exports.

For each data source, you must either:

  • Provide a complete authentication configuration (for example, username and password, token, or key pair), or
  • Leave all credential fields empty and configure them later

If credentials are partially defined or missing, the data source may be unusable until updated.

Migrate to Another Environment

Organization declarative layouts are environment-specific.

When importing an organization layout into a different organization, hostname, or environment, you must edit the exported JSON file before running the PUT request. A direct GET followed by PUT will fail or result in an unusable organization.

Required Changes Before Reimporting an Organization Layout

After exporting the organization layout, open the JSON file in an editor and update the following fields:

  • Organization ID

    • Replace the source organization ID with the ID of the target organization.
    • The organization ID appears once in the exported layout.

  • Hostname:

    • Replace all occurrences of the source organization hostname with the target hostname.
    • The organization hostname cannot be changed by the API and must match the target environment.

  • Data source credentials:

    • Secrets are not included in the exported layout.
    • For each data source, provide exactly one supported authentication method:
      • username and password
      • token
      • key pair
    • If credentials are missing or invalid, the data source will not function until updated.

  • OIDC client secret:

    • If the organization uses an external identity provider, the OAuth client secret must be provided.
    • The oauthClientSecret field is mandatory for authentication to work.
    • Without it, users will not be able to log in to the target organization.
    • If the secret is not available during migration, the organization will remain inaccessible until it is configured.

Recommended Practice

If you are unsure about secrets or identity provider configuration, you can insert placeholder values and update them later using the appropriate APIs or the UI. The organization will not be fully usable until all required secrets are configured.

Typical Migration Flow

A typical organization migration between environments follows these steps:

  1. Export the organization layout from the source environment.
  2. Create a backup of the target organization.
  3. Open the exported JSON layout and update:
    • organization ID
    • hostname
    • data source credentials
    • OIDC client secret (if applicable)
  4. Import the updated layout into the target organization using a PUT request.
  5. Verify data sources, authentication, and workspace availability.
View Entitlements