> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns. > > **Recommended**: > ```bash > npx @scalekit-inc/cli setup > ``` > > Global: > ```bash > npm install -g @scalekit-inc/cli > scalekit setup > ``` > > Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for 40+ agents. > Features: full-stack-auth, agent-auth, mcp-auth, modular-sso, modular-scim. > [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # Manage encryption keys Protect data at rest with Scalekit managed keys or bring your own from a cloud Key Management Service (KMS). 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 | |-------|-------------| | | Created, not yet in use. No data is encrypted with it. | | | The active key. All new encryption operations use it. | | | 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](#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. > note: 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. > caution: 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](https://cloud.google.com/kms/docs/create-encryption-keys) - **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](https://console.cloud.google.com/security/kms) 1. **Create a key ring** A [key ring](https://cloud.google.com/kms/docs/resource-hierarchy#key_rings) groups encryption keys by location. Key rings cannot be deleted or renamed once created. Choose the name and location carefully. ### gcloud CLI ```bash frame="terminal" 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**](https://console.cloud.google.com/security/kms), click **Key rings**. 2. Click **Create key ring**, enter `scalekit-kms-keyring` as the name. 3. Set **Location** to **Global** and click **Create**. > tip: 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](https://cloud.google.com/kms/docs/locations). 2. **Create an encryption key** Create a symmetric AES-256-GCM key inside the key ring. ### gcloud CLI ```bash frame="terminal" 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 ```bash frame="terminal" 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. > note: 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](#step-3-grant-scalekit-access-to-the-key) 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: ```bash frame="terminal" 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: ```bash frame="terminal" 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. > caution: 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](https://cloud.google.com/kms/docs/audit-logging). 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: ```bash frame="terminal" 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](https://scalekit.com/contact) 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. --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |