Backups

Cloud-IAM Console - Backups Feature

Why export your backups from your managed Keycloak?

At Cloud-IAM, we firmly believe that your data belongs to you, and you should have the ability to retrieve and store it within your own infrastructure. With backups feature, Cloud-IAM allows you to easily export complete backups of the PostgreSQL database associated of your deployment.

Export backups are useful when you need to:

• Back up your environment on your own infrastructure
• Increase your redundancy and resilience in the event of a major outage from Cloud-IAM
• Ensure reversibility and data sovereignty if you decide to unsubscribe from Cloud-IAM
• Keep a local or offline backups of your data for compliance or auditing

With Cloud-IAM Managed Keycloak solution you always stay in control, you have the complete ownership of your data. The backups are kept 30 days on the Cloud-IAM storage.

What does backups history contain?

From Cloud-IAM console, each backup entry displays the following information:

• File name: The name of the backup file
• File size: The total size of the file in (MB)
• Creation date: The date and time when the backup was generated
• GPG Key ID(s): The identifier(s) of the GPG key(s) used to encrypt the backup

Cloud-IAM Console - Backups history feature

How to configure backups frequency?

Follow these steps to define the scheduled frequency and start time for your backups:

1. Open Cloud-IAM console
2. Select the Keycloak deployment you want to configure.
3. Click on Pilot
4. Select Settings from backups section
5. Specify Time,UTCand Frequency
6. Then click on Save to confirm the backup frequency.

Once scheduled, next backups will be based on your new configuration.

Cloud-IAM Console - Backups Scheduling Access

How to configure backups locations?

Follow these steps to define the locations of your backups:

1. Open Cloud-IAM console
2. Select the Keycloak deployment you want to configure.
3. Click on Pilot
4. Select Settings from backups section
5. Specify the cloud provider location(s) for your backups from the drop-down list.
6. Then click on Save to confirm the location(s).

Once configured, next backups will be based on your new configuration.

Cloud-IAM Console - Backups Locations Access

How to create a GPG key and import on Cloud-IAM console

If you want to use these backups, you need to register your public GPG key via the Cloud-IAM console on your organization settings. GPG (GNU Privacy Guard) is used for asymmetric encryption. Cloud-IAM will use your public key to encrypt the backup files, which can only be decrypted using the corresponding private key in your possession.

This approach ensures that only you, holding the private key, can access the unencrypted backup data. Once added, all future backups will be encrypted using both Cloud-IAM's internal GPG keys and all valid public keys associated with your organization. This ensures that you retain the ability to securely decrypt and restore backups within your own infrastructure.

To proceed and create and add your GPG key in your organization, follow the step-by-step guide.
👉 Create and Add GPG Key in your organisation

How to download keycloak backups through Cloud-IAM console?

Follow these steps to export your Keycloak data:

1. Open Cloud-IAM console
2. Select the Keycloak deployment you want to download backup.
3. Click on Pilot
4. Select List from backups section
5. Then Click on ↓ to download the backup from backups history

After few second you will get access to a single .gpg file containing PostgreSQL database associated of your deployment.

Cloud-IAM Console - Backups Access

How to download Keycloak backups through the Cloud-IAM API

You can automate backup downloads programmatically using the Cloud-IAM REST API, which is useful for CI/CD pipelines, scheduled scripts, or any automated workflow.

Before making API calls, obtain a Bearer token using a Service Account. See How to authenticate with the Cloud-IAM API for details.

The download process involves 3 steps:

Step 1 — List available backups

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.cloud-iam.com/deployments/{deploymentId}/backups/"

Example response:

{
  "_embedded": {
    "backups":
    [
      {
        "coldBackupId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "filename": "backup-2026-03-02T03-00-00.tar.gz.gpg",
        "status": "BACKUP_API_FINISHED",
        "updatedAt": "2026-03-02T03:12:45Z",
        "locations": ["Scaleway", "Outscale"]
      }, ...
    ]
  },
  "page": {
    "totalElements": 12,
    "totalPages": 1
  }
}

Key response fields:

• coldBackupId — the backup identifier required for the next steps
• filename — the backup filename
• status — must be BACKUP_API_FINISHED for the backup to be downloadable
• updatedAt — backup creation timestamp
• locations — storage providers where the backup is held
• page.totalElements / page.totalPages — pagination info

TIP

The content array is sorted by most recent first. Use content[0] to always work with the latest available backup.

Step 2 — Request a download link

Use the coldBackupId from the previous step to obtain a time-limited and tracked download URL:

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.cloud-iam.com/backups/{coldBackupId}/download-link"

Example response:

{
  "url": "https://api.cloud-iam.com/backups/a1b2c3d4-e5f6-7890-abcd-ef1234567890/download"
}

Step 3 — Download the backup file

Use the url returned in the previous step to download the backup:

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -o backup.tar.gz.gpg \
  "https://api.cloud-iam.com/backups/{id}/download"

The -o flag saves the file locally. The downloaded file is GPG-encrypted.

How to restore a Backup

After downloading the backup to your infrastructure, we strongly recommend storing it securely and keeping it encrypted until restoration is required.

Step 1 - Make your decryption key available on the restore machine

Backups are encrypted with the public GPG key(s) registered on your organization. Decryption therefore requires the matching secret key material to be present in the GPG keyring of the machine performing the restore.

If the restore happens on the same machine where you generated the key pair, that key material is already in your keyring and you can go straight to Step 2. If it happens anywhere else (a recovery server, a CI runner, a new workstation), you need to export it and import it there.

Only the encryption subkey is needed to decrypt a backup. Keep your primary secret key on your key-management machine: it carries the signing and certification capabilities, so whoever holds it can also sign on behalf of your GPG identity, certify other keys, or revoke yours.

1. On the machine holding the key pair, identify the encryption subkey, marked [E]:

$ gpg --list-secret-keys --keyid-format LONG my-email@acme.inc

A sample output might look like this:

sec   rsa3072/9E19788B707738D7 2025-06-26 [SC] [expires: 2026-07-02]
      7D42BCE0C837A8D0F369C8A39E19788B707738D7
uid                 [ultimate] for-ops (none) <my-email@acme.inc>
ssb   rsa3072/4C1BDA5F2A98E311 2025-06-26 [E] [expires: 2026-07-02]

Here the sec line is the primary key, which stays on this machine, and the ssb line marked [E] is the encryption subkey to export, with key ID 4C1BDA5F2A98E311.

2. Export that subkey only, in ASCII-armored format. The trailing ! is required: without it, GPG exports every subkey of the key pair.

$ gpg --output my-email@acme.inc.subkey.pgp.txt --armor --export-secret-subkeys 4C1BDA5F2A98E311!

WARNING

Do not use gpg --export-secret-keys for a restore: it also exports your primary secret key, which the restore does not need. The exported subkey is sensitive too, since it decrypts every backup encrypted for it. Transfer it only over a secure channel, never by email or chat, and delete the exported file from both machines once the import is done.

3. On the restore machine, import the subkey:

$ gpg --import my-email@acme.inc.subkey.pgp.txt

You will be prompted for the passphrase protecting the key material.

4. Confirm the subkey is now available:

$ gpg --list-secret-keys --keyid-format LONG

sec#  rsa3072/9E19788B707738D7 2025-06-26 [SC] [expires: 2026-07-02]
      7D42BCE0C837A8D0F369C8A39E19788B707738D7
uid                 [ unknown] for-ops (none) <my-email@acme.inc>
ssb   rsa3072/4C1BDA5F2A98E311 2025-06-26 [E] [expires: 2026-07-02]

The # after sec means the primary secret key is absent from this keyring, which is exactly what you want. The ssb line is present, so the backup can be decrypted here.

TIP

To check which key material can decrypt a given file, read its recipients:

$ gpg --list-packets "${BACKUP_FILE}.gpg" | grep keyid

Each returned key ID is an encryption subkey the file was encrypted for, one of them being a Cloud-IAM internal key. If none of them matches a subkey you hold, the backup cannot be decrypted on your side. This typically happens when the backup was created before your public key was registered on your organization, or after that key expired. The GPG Key ID(s) column of the backups history in the console tells you which organization keys were used for a given backup.

Step 2 - Decrypt the backup file

Use the following command, to decrypt the file using your private GPG key:

$ gpg --output "$BACKUP_FILE" --decrypt "${BACKUP_FILE}.gpg"

This command will generate a decrypted version of the backup file.

Step 3 - Restore the backup

Use the following command, to restore the backup into a fresh PostgreSQL database:

$ pg_restore -v --host=${DB_ADDR} --port=${DB_PORT} --user=${DB_USER} -Fc -c -d ${DB_DATABASE} ${BACKUP_FILE}