Bring Your Own Key (BYOK)

BYOK lets your organization encrypt all tenant data encryption keys (DEKs) with a KMS key you own and control in your own Google Cloud project. DataRecs uses envelope encryption — your KMS key wraps the DEKs, and only your tenant service account can access it.

Overview

Encryption sovereignty

Your KMS key encrypts all DEKs. Disable the key and DataRecs cannot decrypt your data — you have absolute control.

Zero-downtime migration

DEK re-encryption happens in the background. Your reconciliation jobs and API access continue uninterrupted.

Fully reversible

Revert to platform-managed encryption at any time — DEKs are re-encrypted with the platform KMS key.

Key rotation safe

KMS key rotation creates new versions. Old versions still decrypt existing DEKs — no data loss on rotation.

Prerequisites

1. A Google Cloud KMS key in your own GCP project (any location).

2. Find your tenant service account — it’s shown in the Console under Settings → Encryption, or via the API:

   curl -H "Authorization: Bearer $API_KEY" \
     https://api.datarecs.io/tenant-encryption/config

   The response includes tenant_service_account, a tenant-<your_tenant_id>@<project>.iam.gserviceaccount.com address — copy the exact value, don’t construct it yourself.

3. Grant access to that service account on your key:

   gcloud kms keys add-iam-policy-binding YOUR_KEY_NAME \
     --keyring=YOUR_KEYRING \
     --location=global \
     --project=YOUR_PROJECT \
     --member="serviceAccount:<the tenant_service_account value from step 2>" \
     --role="roles/cloudkms.cryptoKeyEncrypterDecrypter"

Configuring BYOK

Send the KMS key details to DataRecs. This validates access (round-trip encrypt/decrypt test) and immediately starts the migration:

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gcp_project_id": "your-gcp-project",
    "keyring_name": "your-keyring",
    "key_name": "your-key"
  }' \
  https://api.datarecs.io/tenant-encryption/config

Response:

{
  "status": "in_progress",
  "started_at": "2026-01-15T10:30:00.000Z",
  "message": "BYOK configuration saved and migration started. DEKs are being re-encrypted with your KMS key."
}

Monitoring Progress

Check migration status at any time:

curl -H "Authorization: Bearer $API_KEY" \
  https://api.datarecs.io/tenant-encryption/config

The byok_migration_status field shows:

• in_progress — DEKs are being re-encrypted
• completed — All DEKs encrypted with your key
• failed — An error occurred (see byok_migration_error)
• not_started — No migration triggered yet

Reverting to Platform Encryption

To revert back to platform-managed keys:

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  https://api.datarecs.io/tenant-encryption/revert

This re-encrypts all DEKs with the platform KMS key. After completion, your KMS key is no longer used and you can revoke access.

Key Management Best Practices

Key lifecycle

• Key rotation is safe — KMS automatically uses old versions to decrypt existing ciphertext
• Disabling the key makes your data inaccessible until re-enabled (DataRecs will return errors on all data operations)
• Destroying the key makes data permanently inaccessible — there is no recovery

Action	Impact	Reversible?
Rotate key	None — old versions decrypt existing data	N/A
Disable key version	Data temporarily inaccessible	Yes — re-enable
Destroy key version	Permanent data loss	No
Revoke SA access	Data inaccessible until re-granted	Yes

How It Works

1. DataRecs uses envelope encryption: a Data Encryption Key (DEK) encrypts your data, and a Key Encryption Key (KEK) wraps the DEK.
2. On BYOK migration, the platform re-encrypts each DEK by decrypting it with the platform KEK, then encrypting it with your BYOK KEK.
3. After migration, all new encryption operations use your key via the tenant service account’s impersonated access.
4. The DEKs themselves don’t change — only the wrapping key changes. Your data files are untouched.