Use customer-managed encryption keys

Northflank stores your secrets encrypted at rest in its internal database and decrypts them when needed. This protection covers all secrets stored in that database. Examples include:

• Build and runtime values and files, including those in secret groups and global secrets
• Platform-generated secrets, such as addon connection strings
• Integration credentials, including BYOC credentials

By default, Northflank uses its own keys to encrypt these secrets. With customer-managed encryption keys (CMEK), you can use your own key to protect secrets owned by a team or organization. Your key stays in your KMS. Enabling CMEK applies to new encrypted writes and does not automatically re-encrypt existing secrets.

An organization's customer-managed key does not automatically apply to its teams. Each team manages its encryption separately.

Customer-managed encryption does not cover volumes, other workload storage, your application data, addon databases, or backups.

Northflank supports three encryption modes for new encrypted writes:

The Current encryption panel shows the mode for new encrypted writes.

Enabling or changing a mode applies to new encrypted writes, including updates that save encrypted values. It does not automatically convert existing data. Contact support to migrate existing envelope-encrypted data.

Northflank uses envelope encryption to support customer-managed encryption keys (CMEK). It uses two types of keys: a data encryption key (DEK) encrypts your secrets, and a key encryption key (KEK) encrypts, or wraps, the DEK.

With customer-managed encryption, your KMS holds the KEK and wraps and unwraps DEKs. The KEK stays in your KMS, and your secrets are never sent to it. With Northflank-managed envelope encryption, Northflank holds the KEK.

To read a secret with customer-managed encryption, Northflank asks your KMS to unwrap the DEK, then uses it to decrypt the secret. Without access to the KEK, the stored data cannot be decrypted.

Northflank can temporarily cache unwrapped DEKs in memory and reuse them across secrets without contacting your KMS each time. As a result, KMS audit logs do not provide a complete record of secret reads. You can adjust this behavior through the DEK reuse and caching options.

With customer-managed encryption, you control your KMS key and Northflank's access to it. Northflank does not keep a copy of the key.

Use role-based access control to grant encryption permissions separately for teams and organizations. You need Read to view encryption configurations and status. You also need Create to add encryption configurations. Manage lets you edit, activate, or deactivate configurations. It also lets you enable Northflank-managed envelope encryption. Read is still required to use these controls in the UI.

Select your team or organization before you open Settings → Encryption.

Each encryption configuration contains the credentials and key location for one KMS provider.

Before you start, review the prerequisites and your responsibilities for key availability.

To create a new encryption configuration:

1. Open Settings → Encryption for your team or organization.
2. Click Add encryption configuration. If configurations already exist, click Create encryption configuration above All configurations.
3. Under Basic information, enter a unique Name and an optional Description.
4. Select a Provider.
5. Follow the setup instructions for your provider in Connect a KMS provider.

You can leave Advanced options blank to use the defaults.

Creation opens the configuration details with status Pending activation. Saving a configuration does not enable it. Complete the activation procedure when you are ready to use it.

Activating an encryption configuration affects only new encrypted writes. Review your responsibilities for key availability before you continue.

To activate a configuration:

1. Open the configuration from Settings → Encryption.
2. Click Verify.
3. Wait for Verification successful.
4. Click Set as active configuration.
5. Read and select each acknowledgement about key availability, permanent key loss, and existing data.
6. Click Set as active configuration in the dialog.
7. Wait for the configuration to show Active.

Activation checks KMS access once more, then switches new encrypted writes to this configuration. Only one configuration is active at a time. Activation does not change how existing secrets are encrypted. Previously active configurations must remain available to decrypt them. To move existing data to the new key, contact Northflank support.

You can use Verify again to test whether your KMS is accessible and can wrap and unwrap data keys. This does not test whether previously wrapped data keys can still be unwrapped.

If you plan to use your own KMS later, you can start with Northflank-managed envelope encryption for new and updated secrets. Northflank support can migrate this data to use your key when you are ready.

To enable it:

1. Open Settings → Encryption for your team or organization.
2. Under Key management options, click Enable envelope encryption.
3. Wait for Current encryption to show Northflank-managed envelope encryption.

Once enabled, the page no longer offers the opt-in action. If an encryption configuration is active, deactivating it switches new encrypted writes to Northflank-managed envelope encryption.

Use Edit settings to update credentials or change the key location for an encryption configuration. You cannot change the provider.

Northflank does not display stored secret values, so credential fields start empty when you edit a configuration.

You cannot change the GCP authentication method in the edit form. GCP cross-project configurations keep their generated service account and need no credentials. For these configurations, you can edit only the key location.

To make changes to an encryption configuration:

1. Open the configuration from Settings → Encryption.
2. Click Edit settings.
3. If your configuration uses credentials that you supply, re-enter them.
4. To change the key location, enter the new location.
5. If available, click Validate to test the new settings without saving.
6. Click Save settings.
7. Optionally, click Verify on the details page to test the saved configuration.

When you save changes after first activation, Northflank tests KMS access and makes sure that the configuration still points to the same key.

To change DEK rotation or caching, use Advanced options on the details page.

Deactivation stops Northflank from using the active encryption configuration for new encrypted writes. These writes will use Northflank-managed envelope encryption instead.

Previously active encryption configurations must remain valid so Northflank can decrypt existing data. Keep their keys and credentials available, as described in your responsibilities for key availability.

To deactivate the active encryption configuration:

1. Open the active configuration from Settings → Encryption.
2. Click Deactivate.
3. Read and select each acknowledgement about new writes, key availability, and existing data.
4. Click Deactivate in the dialog.
5. Return to the encryption page.
6. Wait for Current encryption to show Northflank-managed envelope encryption.

The previous configuration remains in the list. Its status and data-key count describe its remaining use. For migration, see Rotate keys and migrate data.

The All configurations table shows each customer-managed configuration and its status:

The Retained for decryption notice links to inactive configurations that still hold data keys.

The Data keys count measures stored DEKs, not individual secrets. Multiple secrets can share a DEK. The count can remain unchanged after you delete a secret. It excludes Northflank-managed configurations and data under default encryption.

Follow the key-availability guidance before you retire a key.

The Advanced options section controls DEK reuse and caching for an encryption configuration.

You can configure the following options. Blank fields use the listed defaults:

The lifetime does not delete a key or expire its encrypted data. A DEK that no longer encrypts new data can still decrypt existing data.

To change these values:

1. Open the configuration from Settings → Encryption.
2. Under Advanced options, enter whole numbers in the displayed units, or clear a field to restore its default.
3. Click Save options.

Lower reuse limits and shorter cache periods can increase KMS requests, latency, and provider costs.

Configure key rotation in your KMS according to your policy. Rotation does not migrate existing data. Keep previous key versions available while data still depends on them.

For Azure, a versionless key URL follows rotation for new DEK wrapping. A versioned URL remains pinned to its specified version.

To switch to a different key or KMS provider, create and activate a new encryption configuration. The new configuration applies only to new encrypted writes.

To move existing envelope-encrypted data to the new key, contact Northflank support. Northflank support can also migrate data to or from Northflank-managed envelope encryption.

Follow the key-availability guidance throughout the migration. Keep previous keys available until Northflank support confirms that migration is complete.

To stop using an encryption configuration for new writes, deactivate it.

To block Northflank from decrypting existing secrets, revoke its access to the key in your KMS. Operations that require access to that key fail until access is restored.

Cached data keys can still decrypt secrets until their cache TTL expires, up to five minutes by default.

Revocation does not remove secrets already delivered to workloads.