Manage encryption keys

Scalekit automatically protects data at rest with encryption keys. You can use Scalekit-managed keys or bring your own from a cloud Key Management Service (KMS) provider if your compliance policy requires you to own and control the root key. This guide shows you how to view and manage keys in the dashboard and set up Bring Your Own Key (BYOK) with GCP Cloud KMS.

Key types

Type	Description
Scalekit managed Data Encryption Key (DEK)	Scalekit generates and manages the key. No setup required.
Bring your own key (BYOK)	You provide a key from your own KMS. You own the key lifecycle, including rotation and revocation.

Key states

State	Description
Staged	Created, not yet in use. No data is encrypted with it.
Primary	The active key. All new encryption operations use it.
Deprecated	Replaced by a newer key. Existing records may still reference it until re-encryption completes.

Manage keys

Go to Settings and open the Encryption keys tab.

1. Create a key

   Click Create New Key and select a provider:

   • Scalekit Managed DEK: Scalekit generates and manages the key. Click Create.
   • BYOK - GCP Cloud KMS: Complete Set up BYOK with GCP KMS first to create the GCP key and grant access, then enter the key resource name here and click Create.

   The key is created in Staged state.

2. Activate the key

   Click Activate on a Staged key. The key becomes Primary and Scalekit uses it for all new encryption operations.

   One primary key at a time

   Creating a new key does not replace the current Primary key. The new key stays Staged until you explicitly activate it.

3. Re-encrypt existing data

   To apply the new key to existing records, click Re-encrypt Data. Scalekit decrypts each existing record with the previous key and re-encrypts it with the new key.

Set up BYOK with GCP KMS

Use BYOK to register an encryption key from Google Cloud KMS that your team owns and controls. Scalekit uses the KMS API for all encrypt and decrypt operations and never stores the key material.

You own the key lifecycle

BYOK gives you direct control over your encryption key. Scalekit cannot rotate or manage the GCP key on your behalf. If the key is disabled, destroyed, or Identity and Access Management (IAM) access is revoked, Scalekit cannot encrypt new data or decrypt existing records until you restore access.

Prerequisites

• A Google Cloud project with the Cloud KMS API enabled
• IAM permissions to create key rings, keys, and set key-level IAM policies
• The Scalekit service account email, shown in the Scalekit dashboard when you select BYOK
• gcloud CLI installed and authenticated, or access to the GCP Console

1. Create a key ring

   A key ring groups encryption keys by location. Key rings cannot be deleted or renamed once created. Choose the name and location carefully.

   gcloud CLI

   gcloud kms keyrings create "scalekit-kms-keyring" \
     --location "global" \
     --project "YOUR-GCP-PROJECT"

   Replace YOUR-GCP-PROJECT with your Google Cloud project ID.

   GCP Console
   1. Open Security > Key management, click Key rings.
   2. Click Create key ring, enter scalekit-kms-keyring as the name.
   3. Set Location to Global and click Create.

   Choose the right location

   Use global if your Scalekit environment has no regional data-residency requirement. For region-specific compliance, choose a location such as us-east1 or europe-west1. See Cloud KMS locations.

2. Create an encryption key

   Create a symmetric AES-256-GCM key inside the key ring.

   gcloud CLI

   gcloud kms keys create "scalekit-kms-key" \
     --location "global" \
     --keyring "scalekit-kms-keyring" \
     --purpose "encryption" \
     --project "YOUR-GCP-PROJECT"

   GCP Console
   1. Click the key ring you created, then click Create key.
   2. Enter scalekit-kms-key as the name.
   3. Set Protection level to HSM (recommended) and click Continue.
   4. Set Key material to HSM-generated and click Continue.
   5. Set Purpose to Symmetric encrypt/decrypt and click Continue.
   6. Set Rotation period per your policy and click Create.

3. Grant Scalekit access to the key

   Grant both roles at the key level to limit Scalekit’s IAM access to this specific key.

   Role	Purpose
   roles/cloudkms.cryptoKeyEncrypterDecrypter	Encrypt and decrypt the DEK
   roles/cloudkms.viewer	Read key metadata for health checks and listing

   gcloud CLI

   gcloud kms keys add-iam-policy-binding "scalekit-kms-key" \
     --keyring "scalekit-kms-keyring" \
     --location "global" \
     --project "YOUR-GCP-PROJECT" \
     --member "serviceAccount:SCALEKIT-SERVICE-ACCOUNT" \
     --role "roles/cloudkms.cryptoKeyEncrypterDecrypter"
   
   gcloud kms keys add-iam-policy-binding "scalekit-kms-key" \
     --keyring "scalekit-kms-keyring" \
     --location "global" \
     --project "YOUR-GCP-PROJECT" \
     --member "serviceAccount:SCALEKIT-SERVICE-ACCOUNT" \
     --role "roles/cloudkms.viewer"

   GCP Console
   1. In the GCP Console, open Security > Key management, click Key rings, then click the key ring name.
   2. Click the key name, then open the Permissions tab.
   3. Click Grant access. A side panel opens.
   4. In the New principals field, enter the Scalekit service account email. Copy it from Settings > Encryption keys > Create New Key > BYOK - GCP Cloud KMS in the Scalekit dashboard.
   5. In the Assign Roles section, select Cloud KMS CryptoKey Encrypter/Decrypter from the first Role dropdown.
   6. Click + Add another role and select Cloud KMS Viewer.
   7. Click Save. The policy update takes effect within a few minutes.

   Key-level vs project-level IAM

   Grant these roles at the key level to limit Scalekit’s access to only this specific key.

4. Register the key in Scalekit

   • In the Scalekit dashboard, go to Settings and open the Encryption keys tab.
   • Click Create New Key and select BYOK - GCP Cloud KMS.
   • Copy the Scalekit service account email shown in the modal. You need it for step 3 if you have not granted IAM access yet.
   • Enter the fully-qualified GCP key resource name:

   projects/YOUR-GCP-PROJECT/locations/global/keyRings/scalekit-kms-keyring/cryptoKeys/scalekit-kms-key

   To retrieve the exact name from the CLI:

   gcloud kms keys describe "scalekit-kms-key" \
     --keyring "scalekit-kms-keyring" \
     --location "global" \
     --project "YOUR-GCP-PROJECT" \
     --format="value(name)"

   • Click Create. The key is created in Staged state.
   Key resource name format

   The key reference must follow this format:

   projects/{PROJECT_ID}/locations/{LOCATION}/keyRings/{KEYRING_NAME}/cryptoKeys/{KEY_NAME}

   To retrieve the key ring path:

   gcloud kms keyrings describe "scalekit-kms-keyring" \
     --location "global" \
     --project "YOUR-GCP-PROJECT" \
     --format="value(name)"

   Append /cryptoKeys/scalekit-kms-key to get the full key reference.

5. Activate the key

   Click Activate on the staged key. The key becomes Primary and Scalekit uses it for all new encryption operations.

   Activation is permanent

   Once activated, you cannot deactivate the key without creating and activating a new key. Confirm your IAM grants are in place before activating.

6. Re-encrypt existing data

   Activation covers new writes automatically. Click Re-encrypt Data to migrate existing records. Scalekit decrypts each record with the previous key and re-encrypts it with the new key.

Monitor with audit logs

Cloud KMS logs every cryptographic operation to Cloud Audit Logs. Use this filter in Cloud Logging to see all encrypt, decrypt, and key events for your key:

resource.type="cloudkms_cryptokey"

Fix common errors

Permission denied when activating or using the key

Check that both IAM bindings are applied to the correct key:

gcloud kms keys get-iam-policy "scalekit-kms-key" \
  --keyring "scalekit-kms-keyring" \
  --location "global" \
  --project "YOUR-GCP-PROJECT"

The output should list the Scalekit service account with both roles/cloudkms.cryptoKeyEncrypterDecrypter and roles/cloudkms.viewer. If the bindings are missing, repeat step 3.

Re-encryption reports unrecoverable rows

Unrecoverable rows are records that could not be re-encrypted, typically because the previous key version was disabled or destroyed before re-encryption completed.

Contact Scalekit support if you need help recovering affected records.

Key resource name is not accepted

Verify the format is exactly:

projects/PROJECT_ID/locations/LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME

Run gcloud kms keys describe with --format="value(name)" to retrieve the exact string. Do not construct it manually.