Security & Compliance

Bring Your Own Key (BYOK)

Enterprise Add-on. Contact sales to enable BYOK for your account.

Overview

Bring Your Own Key (BYOK) enables you to encrypt your data at rest in Zep using your own Customer Master Key (CMK) stored in your AWS KMS account. This provides full control over your encryption keys, including the ability to revoke Zep’s access at any time.

With BYOK enabled:

  • Your data is encrypted using keys derived from your CMK
  • Zep never has direct access to your CMK—only cross-account usage rights
  • You maintain complete control over key rotation and access revocation
  • All encryption operations are logged in your AWS CloudTrail for auditability

Prerequisites

  • An AWS account with permissions to create and manage KMS keys
  • Your Zep account UUID (available from your Zep dashboard)

Setup instructions

Step 1: Create a KMS key

Create a symmetric KMS key in your AWS account. Zep Cloud operates in us-west-2, so your key must be accessible from that region:

  • Single-region key: Create directly in us-west-2
  • Multi-region key: Create in any region and replicate to us-west-2
$aws kms create-key \
>  --description "Zep BYOK encryption key" \
>  --key-usage ENCRYPT_DECRYPT \
>  --origin AWS_KMS \
>  --region us-west-2

Note the KeyId or Arn from the response—you’ll need this for the next steps.

Optionally, create an alias for easier reference:

$aws kms create-alias \
>  --alias-name alias/zep-byok \
>  --target-key-id <your-key-id> \
>  --region us-west-2
1resource "aws_kms_key" "zep_byok" {
2  description             = "Zep BYOK encryption key"
3  key_usage               = "ENCRYPT_DECRYPT"
4  deletion_window_in_days = 30
5  enable_key_rotation     = true
6
7  # Deploy this resource in us-west-2
8  provider = aws.us-west-2
9}
10
11resource "aws_kms_alias" "zep_byok" {
12  name          = "alias/zep-byok"
13  target_key_id = aws_kms_key.zep_byok.key_id
14
15  provider = aws.us-west-2
16}

Step 2: Grant Zep cross-account access

Configure your KMS key policy to allow Zep’s services to use your key for encryption and decryption. The policy includes an encryption context condition that ensures the key can only be used for Zep operations.

First, retrieve your AWS account ID:

$aws sts get-caller-identity --query Account --output text

Then create and apply the key policy. Replace <your-key-id> with your KMS key ID from Step 1, and <your-aws-account-id> with the 12-digit account ID from above:

$aws kms put-key-policy \
>  --key-id <your-key-id> \
>  --policy-name default \
>  --region us-west-2 \
>  --policy '{
>    "Version": "2012-10-17",
>    "Id": "zep-byok-key-policy",
>    "Statement": [
>      {
>        "Sid": "EnableRootAccountPermissions",
>        "Effect": "Allow",
>        "Principal": {
>          "AWS": "arn:aws:iam::<your-aws-account-id>:root"
>        },
>        "Action": "kms:*",
>        "Resource": "*"
>      },
>      {
>        "Sid": "AllowZepBYOKAccess",
>        "Effect": "Allow",
>        "Principal": {
>          "AWS": "arn:aws:iam::467218391112:role/zep-byok"
>        },
>        "Action": [
>          "kms:GenerateDataKey",
>          "kms:Decrypt"
>        ],
>        "Resource": "*",
>        "Condition": {
>          "StringEquals": {
>            "kms:EncryptionContext:service": "zep"
>          }
>        }
>      }
>    ]
>  }'

For additional security, you can restrict key usage to your specific Zep account UUID. Replace the Condition block in the policy above with:

1"Condition": {
2    "StringEquals": {
3        "kms:EncryptionContext:service": "zep",
4        "kms:EncryptionContext:account_uuid": "<your-zep-account-uuid>"
5    }
6}
1locals {
2  zep_byok_role_arn = "arn:aws:iam::467218391112:role/zep-byok"
3}
4
5# Optional: set to your Zep account UUID for additional restriction
6variable "zep_account_uuid" {
7  description = "Your Zep account UUID"
8  type        = string
9  default     = null
10}
11
12data "aws_caller_identity" "current" {}
13
14data "aws_iam_policy_document" "zep_byok" {
15  statement {
16    sid    = "EnableRootAccountPermissions"
17    effect = "Allow"
18    principals {
19      type        = "AWS"
20      identifiers = ["arn:aws:iam::${data.aws_caller_identity.current.account_id}:root"]
21    }
22    actions   = ["kms:*"]
23    resources = ["*"]
24  }
25
26  statement {
27    sid    = "AllowZepBYOKAccess"
28    effect = "Allow"
29    principals {
30      type        = "AWS"
31      identifiers = [local.zep_byok_role_arn]
32    }
33    actions = [
34      "kms:GenerateDataKey",
35      "kms:Decrypt"
36    ]
37    resources = ["*"]
38
39    condition {
40      test     = "StringEquals"
41      variable = "kms:EncryptionContext:service"
42      values   = ["zep"]
43    }
44
45    dynamic "condition" {
46      for_each = var.zep_account_uuid != null ? [1] : []
47      content {
48        test     = "StringEquals"
49        variable = "kms:EncryptionContext:account_uuid"
50        values   = [var.zep_account_uuid]
51      }
52    }
53  }
54}
55
56resource "aws_kms_key_policy" "zep_byok" {
57  key_id = aws_kms_key.zep_byok.id
58  policy = data.aws_iam_policy_document.zep_byok.json
59}
60
61output "kms_key_arn" {
62  description = "KMS Key ARN to provide to Zep"
63  value       = aws_kms_key.zep_byok.arn
64}
65
66output "aws_account_id" {
67  description = "AWS Account ID to provide to Zep"
68  value       = data.aws_caller_identity.current.account_id
69}

Step 3: Configure BYOK in Zep

Navigate to Account > Encryption in your Zep dashboard and enter your KMS Key ARN. The region and AWS account ID will be extracted automatically from the ARN.

BYOK Configuration

Click Save Configuration to enable BYOK encryption. Zep will validate connectivity to your KMS key.

If validation fails, review your KMS key policy to ensure the AllowZepBYOKAccess statement is correctly configured and that your key ARN is accurate.

New data written after activation will be encrypted with your key.

Key rotation

AWS KMS supports automatic key rotation for customer-managed keys. When enabled, AWS automatically creates new key material annually while retaining old material for decryption.

To enable automatic rotation:

$aws kms enable-key-rotation --key-id <your-key-id>

If using Terraform, key rotation is already enabled via enable_key_rotation = true in the example above.

No action is required from Zep when you rotate keys—AWS KMS handles this transparently.

When AWS KMS rotates your key, it creates a new key version but retains all previous versions. Zep does not re-encrypt existing data with new key versions—data remains encrypted with the key version that was active at the time of encryption.

  • Do not delete old key versions—this will result in permanent data loss for any data encrypted with those versions
  • If you need to delete old key versions for compliance reasons, contact Zep first to coordinate data re-encryption

Revoking access

To revoke Zep’s access to your data:

  1. Remove the AllowZepBYOKAccess statement from your KMS key policy
  2. Contact Zep to disable BYOK for your account

After revocation:

  • New data writes will fail immediately
  • Existing encrypted data will become inaccessible once cached encryption keys expire
  • Your account may be suspended until access is restored or BYOK is disabled

Audit trail

All KMS operations performed by Zep are logged in your AWS CloudTrail with the following encryption context:

1{
2    "service": "zep",
3    "account_uuid": "<your-account-uuid>"
4}

You can use CloudTrail to monitor and alert on key usage patterns.

FAQ

Routine operations do not require manual access to plaintext data. Automated services decrypt data within isolated, audited environments. In exceptional cases—such as a customer-approved incident investigation—access is governed by strict separation of duties, multi-party approvals, and comprehensive logging. You retain the ability to disable your CMK, which immediately blocks further decryption.

All encrypted data becomes unreadable. This is by design: the key is the final arbiter of access. Ensure you have internal procedures for emergency restores before disabling or deleting a key.

No. Zep caches derived data encryption keys securely in memory, so encryption and decryption happen without additional round trips to AWS KMS during live traffic.

Yes. You can enable automatic rotation in AWS KMS. Key versions created through rotation are honored automatically, and data encryption keys are re-wrapped in the background. Disabling the key immediately revokes access.

Yes. All persistent storage and backups for your tenant use envelope encryption derived from your CMK. Stateless services process data in memory and never persist plaintext content.

Customer data remains within us-west-2, Zep Cloud’s region. Data in motion is encrypted with TLS 1.3, and at rest it is encrypted using keys derived from your CMK.

Review the AWS CloudTrail logs generated in your account. Every encrypt, decrypt, and key management action involving your CMK is recorded. Zep maintains corresponding provider-side logs that can be shared under NDA for compliance reviews.

You own the CMK, including rotation, revocation, and IAM policy management. Zep monitors for key state changes and will notify your administrators if a key action affects service availability.

Support

For assistance with BYOK setup, contact your Zep account team or email [email protected].