Managing Encryption Keys

CyborgDB encrypts every index under a 256-bit AES key (the index key, also called the KEK in the service code). Without that key it is impossible to read the index — you cannot query, list, upsert, or even safely delete its contents. v0.17 supports two completely different ways to provision and hold that key. Pick one per index:

Mode	What you set on `create_index`	Who holds the plaintext key	Best for
SDK-supplied	`index_key` (32 bytes)	Your SDK / application	Development, evaluation, single-tenant deployments where you already have a secure key store
KMS-backed	`kms_name` (registry slot)	The service’s KMS (AWS KMS or Secrets Manager)	Production, multi-tenant, BYOK

This page covers the SDK-supplied path. For production, prefer the KMS-backed path — see Per-Index KMS & BYOK for the end-to-end setup.

Do not commit, log, or check in index_key material, and do not store it in plaintext on shared filesystems. Lost keys cannot be recovered — every index wrapped under a lost key becomes permanently unreadable.

Generating a key for development

For local development and evaluation, generate a 256-bit key locally and pass it as index_key (or the SDK’s typed equivalent).

# 32 random bytes, hex-encoded (64 hex chars)
openssl rand -hex 32

from cyborgdb import Client

client = Client(base_url='http://localhost:8000', api_key='your-api-key')

# Generate a 32-byte key; `save=True` writes it to ~/.cyborgdb/index_key
index_key = client.generate_key(save=False)

import { Client } from 'cyborgdb';

const client = new Client({ baseUrl: 'http://localhost:8000', apiKey: 'your-api-key' });

// Returns a fresh 32-byte Uint8Array
const indexKey: Uint8Array = client.generateKey();

import "github.com/cyborginc/cyborgdb-go"

// Returns ([]byte, error)
indexKey, err := cyborgdb.GenerateKey()
if err != nil {
    log.Fatal(err)
}

Using the key

The same index_key you passed to create_index must be re-supplied on every subsequent request for that index — load_index, upsert, query, get, delete, delete_index. The service stores only a hash to verify the key on each request; it never persists the plaintext.

# Create
index = client.create_index('my_index', index_key=index_key, dimension=384)

# Subsequent calls — same key
index = client.load_index('my_index', index_key=index_key)
index.upsert([{'id': 'a', 'vector': [0.1] * 384}])
results = index.query(query_vectors=[0.1] * 384, top_k=5)

// Create
const index = await client.createIndex({
    indexName: 'my_index',
    indexKey,
    dimension: 384,
});

// Subsequent calls — same key
const loaded = await client.loadIndex({ indexName: 'my_index', indexKey });
await loaded.upsert({ items: [{ id: 'a', vector: new Array(384).fill(0.1) }] });
const results = await loaded.query({ queryVectors: new Array(384).fill(0.1), topK: 5 });

dim := int32(384)

// Create
index, _ := client.CreateIndex(context.Background(), &cyborgdb.CreateIndexParams{
    IndexName: "my_index",
    IndexKey:  indexKey,
    Dimension: &dim,
})

// Subsequent calls — same key
loaded, _ := client.LoadIndex(context.Background(), "my_index", indexKey)
_ = loaded.Upsert(context.Background(), cyborgdb.VectorItems{
    {Id: "a", Vector: []float32{ /* 384 values */ }},
})

INDEX_KEY=$(openssl rand -hex 32)

# Create
curl -X POST "http://localhost:8000/v1/indexes/create" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d "{
       \"index_name\": \"my_index\",
       \"index_key\": \"$INDEX_KEY\",
       \"dimension\": 384
     }"

# Subsequent calls — same hex key
curl -X POST "http://localhost:8000/v1/indexes/describe" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d "{
       \"index_name\": \"my_index\",
       \"index_key\": \"$INDEX_KEY\"
     }"

Persisting the key

The service never persists the plaintext key, so your application owns key storage. For development, the Python SDK’s generate_key(save=True) will cache the generated key in ~/.cyborgdb/index_key — useful for evaluation, not for production. For production:

Store the key in your platform’s secret store (Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, k8s Secret) and fetch it at runtime.
Or switch to the KMS-backed path so the SDK never holds a long-term key: see Per-Index KMS & BYOK.

Migrating from SDK-supplied to KMS-backed

You cannot rotate an index in place from provider: none to a real KMS provider — the wrapping model changes. The migration path is:

Create a new index with kms_name set instead of index_key.
Replay your data (upsert) into the new index.
Delete the old index.

This is intentional: the persisted envelope for provider: none records no wrap key, so there is nothing for the KMS path to unwrap. Bulk re-encryption against a fresh DEK happens on the upsert.

CyborgDB Service

Encrypted Indexes

Data Operations

Advanced

Managing Encryption Keys

Generating a key for development

Using the key

Persisting the key

Migrating from SDK-supplied to KMS-backed

See also

​Generating a key for development

​Using the key

​Persisting the key

​Migrating from SDK-supplied to KMS-backed

​See also

Generating a key for development

Using the key

Persisting the key

Migrating from SDK-supplied to KMS-backed

See also