Master Key Rotation

Updated Jan 21, 2026 Edit this page

Master Key Rotation

The Master Encryption Key (ACT_MASTER_KEY) is the root of trust for your ACT installation. It encrypts all sensitive data at rest, including:

  • Server SSH Private Keys & Passphrases
  • Service Environment Variables
  • Environment Variables (Environment-level)
  • Git Access Tokens
  • Registry Credentials
  • Storage Provider Secrets

When to Rotate

You should rotate your Master Key if:

  1. You suspect the act.env file or the environment variables have been compromised.
  2. An administrator with access to the server has left the organization (and had access to the raw key).
  3. As part of a regular security compliance schedule (e.g., annually).

The Rotation Process

ACT provides an automated API endpoint to handle the complex process of re-encrypting your database.

⚠️ WARNING: This is a dangerous operation. If the process is interrupted (e.g., power failure) in the middle of the transaction, your database could be left in an inconsistent state (though the database transaction should roll back, external factors can vary). Always backup your database before proceeding.

Step-by-Step Guide

1. Backup Your Database

Ensure you have a full SQL dump of your act database.

# Example for SQLite
cp /var/lib/act/act.db /var/lib/act/act.db.backup

2. Generate a New Key

Generate a new 32-byte hex string. You can use OpenSSL:

openssl rand -hex 32

3. Call the API

Make a POST request to /api/maintenance/rotate-key. You will need your Old Key and the New Key.

curl -X POST https://act.yourdomain.com/api/maintenance/rotate-key \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "old_key": "CURRENT_MASTER_KEY_HEX",
    "new_key": "NEW_GENERATED_KEY_HEX"
  }'

4. Update Configuration

Immediately after receiving a success response, you must update the act.env file on your server with the new key.

# /etc/act/act.env
ACT_MASTER_KEY=<NEW_GENERATED_KEY_HEX>

5. Restart ACT

Restart the service to load the new key.

sudo systemctl restart act

Troubleshooting

  • “Integrity canary not found”: This entails your database is corrupted or was never initialized correctly with an integrity check.
  • “Old master key incorrect”: The key you provided in old_key does not match the one currently encrypting the data.