Skip to main content

Back up and restore tenants

Use the SecureAuth tenant export/import APIs to back up and restore your tenant. The export API retrieves the current configuration, which you can store securely (e.g., in a private repository). The import API restores the configuration when needed.

Export limitations for workspaces​

The export API doesn't directly support workspace exports.

To restore a specific workspace, extract its data from the JSON provided by the export API. Include the server object and any objects with a server_id matching the workspace's ID. Keep in mind that tenant-specific data (e.g., authentication context) may prevent a fully functional workspace restore.

Back up and restore your tenant​

Prerequisites​

  • Get an access token from a client in your tenant's system workspace with the manage_configuration scope

  • Use jq to process data in the examples

Acquire an access token

Run the following command to retrieve the token:

CREDENTIALS="$(echo -n \"${CLIENT_ID}:${CLIENT_SECRET}\" | base64)"
  export TOKEN=$(curl -k -X POST "${ENV_URL}/${TENANT_ID}/system/oauth2/token" \
      -H "Authorization: Basic ${CREDENTIALS}" \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      --data-raw 'grant_type=client_credentials&scope=manage_configuration' | jq -r ".access_token")

Export tenant configuration​

Use the Export Tenant Configuration API to back up the current tenant configuration.

curl -k --request GET \
  --url https://example.com/api/system/{{tid}}/configuration \
  --header "Authorization: Bearer $TOKEN"

Restore tenant configuration​

Requirements

  • Supported on both SaaS and custom deployments with the correct system workspace and client setup.

Use the Import Tenant Configuration API to restore the tenant to a previous state. Include mode=update to prevent errors with existing objects.

curl -i -k --request PUT \
  --url https://example.com/api/system/{{tid}}/configuration\?mode\=update \
  --header "Authorization: Bearer $TOKEN" \
  -d @data.json
note

To update only a specific attribute, include the full object configuration in the request.

Restore any tenant (custom deployments only)​

Prerequisites​

  • Get an access token from a client in the system workspace inside the system tentant with the manage_configuration scope

  • Use jq to process data in the examples

Acquire an access token

Run this command to retrieve the token:

SYSTEM_CREDENTIALS="$(echo -n \"${SYSTEM_CLIENT_ID}:${SYSTEM_CLIENT_SECRET}\" | base64)"
  export SYSTEM_TOKEN=$(curl -k -X POST "${ENV_URL}/system/system/oauth2/token" \
      -H "Authorization: Basic ${SYSTEM_CREDENTIALS}" \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      --data-raw 'grant_type=client_credentials&scope=manage_configuration' | jq -r ".access_token")

Export a tenant configuration​

Use the Export Tenant Root API, specifying the target tenant's tid as query parameter. If you omit tid, the API exports all tenants:

curl -k --request GET \
  --url https://example.com/api/system/configuration\?tid\=${TID} \
  --header "Authorization: Bearer $SYSTEM_TOKEN"

Restore a tenant configuration​

Use the Import Tenant Root API to restore the tenant. Include mode=update to avoid errors.

curl -k --request PUT \
  --url https://example.com/api/system/configuration\?mode\=update \
  --header "Authorization: Bearer $SYSTEM_TOKEN" \
  -d @data.json

The tenant is restored successfully.