How to complete the initial configuration and add new domains to back up using CubeBackup APIs.


CubeBackup allows you to skip the setup wizard using a set of APIs to automate the initial configuration of a CubeBackup instance. You can also integrate CubeBackup into your own systems and accommodate additional domains in a single CubeBackup instance in the future.

Learn how to complete the setup process by following the step-by-step instructions below. A sample script written in Python can also be found in our Git repository.

NOTE: Before following this guide, please be sure to enable the CubeBackup APIs and create an API client on your CubeBackup server.

Add your backup repository

Add an on-premises storage directory or a cloud storage bucket as the backup repository for your CubeBackup instance.

Call the Create the backup storage API, passing along the Storage object as a JSON payload. See the Storage object for a full list of parameters you will need to pass to the API, depending on your storage type.

curl -L \
  --request POST ".../api/v1/storage/settings" \
  --header "Authorization:255c6...88111" \
  --header "Content-Type: application/json" \
  --data '{
    "EncryptEnabled": true,
    "Type": "LOCAL",
    "IndexPath": "/opt/cubebackup/index",
    "DataPath": "/var/cubebackup_data"
}'

CubeBackup will test the required storage permissions, and return the Storage object in the HTTP response if the storage has been successfully configured; otherwise, it will return an error with a detailed Message attribute if the storage is not accessible or the credentials are invalid.

Upload a GCP service account

Upload a GCP service account key as the authentication token for your CubeBackup instance to access and back up your Google Workspace data in the future.

NOTE: You will need to manually create the service account, and authorize domain-wide delegation for it. A service account key file can be downloaded in JSON format directly from GCP.

Call the Upload a service account API, passing along a Service account object as a JSON payload. See the Service account object for a full list of parameters you will need to pass to the API.

curl -L \
  --request POST ".../api/v1/google/sat" \
  --header "Authorization:255c6...88111" \
  --header "Content-Type: application/json" \
  --data '{ 
    "type": "service_account", 
    "project_id": "cubebackup...test", 
    "private_key_id": "03cf6...e1165", 
    "private_key": "-----BEGIN PRIVATE KEY-----\nMIIE...v9zkg\n-----END PRIVATE KEY-----\n", 
    "client_email": "test...iam.gserviceaccount.com", 
    "client_id": "10279...82949", 
    "auth_uri": "https://accounts.google.com/o/oauth2/auth", 
    "token_uri": "https://oauth2.googleapis.com/token", 
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", 
    "client_x509_cert_url": "https://www.googleapis.com/...test.iam.gserviceaccount.com" 
  }'

This API will return "OK" in the response body once the service account is successfully uploaded.

Create a CubeBackup system administrator

Create the first CubeBackup system administrator before completing the setup.

Call the Create a system admin during the initial setup API, passing along the required parameters AdminName, AdminEmail and Password.

curl -L \
  --request POST ".../api/v1/setup/complete" \
  --header "Authorization:255c6...88111" \
  --data AdminName="CubeSysAdmin" \
  --data AdminEmail="[email protected]" \
  --data Password="12...bc"

This API will check the storage and service account setup status first, and return "OK" in the response body once the admin has been successfully created and the initial setup is marked as done.

NOTE: Please add a time delay to let your program sleep for a few seconds before the CubeBackup service restarts after completing the initial setup.

Activate your license

After setting up your CubeBackup instance, you can either start with the 14-day free trial, or pass your CubeBackup license to the Activate a CubeBackup license API to activate your instance directly.

This API requires you to pass along the parameter Code containing a valid CubeBackup license code.

curl -L \
  --request POST ".../api/v1/license/activate" \
  --header "Authorization:255c6...88111" \
  --data Code="P4Q9...DKCC"

A successful request will return the License object containing the expiration date, number of accounts and other attributes of this license, which can be saved for future reference.

Add Google Workspace domains

CubeBackup allows you to back up multiple Google Workspace domains using a single instance. You can use the Add a domain API to add your first Google Workspace domain, or to include additional domains after the initial setup.

Step 1. Authorize domain-wide delegation

Before getting started with this API, please be sure to authorize domain-wide delegation for the new domain. CubeBackup uses the same service account as the authentication token for all domains on one instance. You can retrieve the client ID of this service account using the Retrieve the current service account API.

curl -L ".../api/v1/google/sat" \
  --header "Authorization:255c6...88111"

This call will return a service account object in JSON format. Use the retrieved client_id value to authorize domain-wide delegation in the Google Admin Console.

Step 2. Add a domain

Call the Add a domain API and specify the new domain name and domain administrator using the parameters DomainName and AdminEmail.

curl -L \
  --request POST ".../api/v1/domains" \
  --header "Authorization:255c6...88111" \
  --data DomainName="mydomain.com" \
  --data AdminEmail="[email protected]"

If successful, the response will contain the Domain object; otherwise, an error with a detailed Message attribute will be returned.

Step 3. Update domain status

Domains are initially created with the created Status. To proceed and manage the domain, you will need to update the domain Status to active using the Update a domain API.

curl -L \
  --request PATCH ".../api/v1/domains/mydomain.com" \
  --header "Authorization:255c6...88111" \
  --data "Status=active"

If successful, the response will contain the Domain object; otherwise, an error with a detailed Message attribute will be returned.

Step 4. Configure domain settings

Now you will be able to trigger a backup or configure optional settings for the newly-created domain. See How to automate backup management and license assignment programmatically using CubeBackup APIs for more information.

Add additional CubeBackup administrators (optional)

CubeBackup supports assigning multiple administrators with different levels of permission to manage the backups. See Types of accounts in CubeBackup for Google Workspace for more information.

Best practices for managing multiple domains in CubeBackup are to create multiple administrators with granular permissions for each domain. Call the Create an administrator API, passing along the required parameters Name, Email, Password and Role. See the CubeBackup admin object for a full list of parameters you can pass to the API.

curl -L \
  --request POST ".../api/v1/system/admins" \
  --header "Authorization:255c6...88111" \
  --data Name="Sample Admin" \
  --data Email="[email protected]" \
  --data Password="myPassword" \
  --data Role="cubeDomainAdmin" \
  --data Comment="admin comment" \
  --data Domains="mydomain.com, mydomain2.com"

If successful, the response will contain the CubeBackup admin object; otherwise, an error with a detailed Message attribute will be returned.

Congradulations!

You have now successfully completed the initial setup of a CubeBackup instance. Log in to your CubeBackup web console to start the initial backup, or configure CubeBackup with more options.

You can also proceed with the CubeBackup APIs to see How to monitor the CubeBackup service status (backup / storage / license) programmatically using CubeBackup APIs and How to automate backup and license assignment programmatically using CubeBackup APIs.