Backing up Tenants in a Nutshell

In case you need to back up and restore your tenant, you can do it by leveraging the tenant export/import APIs. You can use the export API to get the current configuration and store the it in a secure location (such as your private repository), and then use the import API to restore it.

Export limitations for Workspaces

The Export API currently does not support workspace export, so if you want to handle specific workspace restore, you have to extract the workspace data from JSON provided by export API. For that purpose, you need to extract the server object and all other objects with server_id matching the ID of the workspace you want to restore. Additionaly, some data (such as authentication context) are tenant-specific and restoring the workspace only may not fully restore it to a working state.

Backup and Restore Your Tenant

Prerequisites

• Access token from client created in the system workspace inside your tenant.

• Additionaly, this client needs to request the manage_configuration scope.

• jq is used in the example below to handle data.

Sample client credentials flow command for acquiring 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

1. Use the Export Tenant Configuration System API in order to export the current tenant configuration.

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

Restore Tenant Configuration

Environment specifics

This instruction is valid on both SaaS and custom Cloudentity deployments. The only requirement is that your workspace system and it’s client still have the correct setup.

1. Using import tenant configuration System API we restore state to old one of whole tenant using previously exported configuration. Note that we provide additional parameter mode=update, without it API request would fail, as provided objects already exists.

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

If you want to only update a specific attribute of an object, you need to provide the entire object configuration.

Restore any Tenant

Environment specifics

This instruction is valid only on custom Cloudentity deployments, where you can access the system tenant’s APIs.

Prerequisites

• Access token from client created in system workspace inside system tenant.

• Additionaly, this client needs to request the manage_configuration scope.

• jq is used in the example below to handle data.

Sample client credentials flow command for acquiring 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 Tenant Configuration

1. Use export tenant Root API with providing target tenant’s tid as query parameter (if you don’t provide it, the API will export all exisitng tenants).

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

Restore Tenant Configuration

1. Use import tenant Root API to restore tenant to state from previously acquired configuration. Note that we provide additional parameter mode=update. Without it, the request would fail, as the provided objects already exist.

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

Your tenant is restored as a result.