Multi-Tenancy & RBAC

CyborgDB Service v0.17 ships with an operator-side multi-tenancy model built on cryptographic isolation: each index is wrapped by its own key, and per-user API keys hold their own wrapped data-encryption keys (DEKs). Permissions aren’t stored as a policy blob — the set of wrapped DEKs a user holds is their permission set, enforced by the encrypted-index engine on every request. This page is the operator playbook: how to enable RBAC, mint and revoke users, and the constraints to be aware of.

Modes

Mode	Enabled by	Who can call what
Single-key (default)	`CYBORGDB_SERVICE_ROOT_KEY` unset	One `CYBORGDB_API_KEY` has full access to everything. No user routes available.
RBAC	`CYBORGDB_SERVICE_ROOT_KEY` set	The root key has admin (mint/list/revoke users, create/train/delete indexes). Per-user `cdbk_…` keys are scoped to one index with `read` / `write` permissions. The legacy `CYBORGDB_API_KEY` is no longer accepted on index routes.

You enable RBAC by setting both keys at startup:

export CYBORGDB_API_KEY=cyborg_your_legacy_key      # still required (license)
export CYBORGDB_SERVICE_ROOT_KEY=cyborg_your_root_key   # opt-in: enables RBAC
cyborgdb-service

Or via YAML:

cyborgdb.yaml

service:
  cyborgdb_api_key: ${CYBORGDB_API_KEY}
  cyborgdb_service_root_key: ${CYBORGDB_SERVICE_ROOT_KEY}

Pick fresh, distinct values for the two keys. The root key has admin privileges; treat it like a master credential. Rotate it independently of CYBORGDB_API_KEY.

Key kinds

When RBAC is on, the service classifies every X-API-Key request header into one of three kinds:

Kind	Header value	What it can do
`root`	`CYBORGDB_SERVICE_ROOT_KEY`	Full admin: create/train/delete indexes; mint/list/revoke users; all data operations.
`user`	A `cdbk_…` token minted via `POST /v1/indexes/{name}/users`	Data operations on one index, gated by the `read` / `write` permission set requested at mint time. Cannot create/delete indexes or manage users.
`legacy`	`CYBORGDB_API_KEY`	Rejected on index routes when RBAC is on. Health endpoint still works.

If CYBORGDB_SERVICE_ROOT_KEY is unset, the legacy single key keeps its full-access behavior — RBAC is strictly opt-in.

Provisioning users

A user is scoped to exactly one index, with a non-empty subset of {"read", "write"} permissions. Mint a user with the root key:

curl -X POST "http://localhost:8000/v1/indexes/documents/users" \
     -H "X-API-Key: $CYBORGDB_SERVICE_ROOT_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "permissions": ["read", "write"]
     }'
# Response (returned ONCE — capture it):
# { "user_id": "ab12…", "api_key": "cdbk_…" }

from cyborgdb import Client

admin = Client(base_url='http://localhost:8000', api_key=ROOT_KEY)
index = admin.load_index('documents')  # KMS-backed: no index_key

result = index.create_user(permissions=['read', 'write'])
user_id = result['user_id']
api_key = result['api_key']
# Hand `api_key` to the new user via a secure channel — it is never recoverable.
# Avoid logging or printing it.

import { Client } from 'cyborgdb';

const admin = new Client({ baseUrl: 'http://localhost:8000', apiKey: ROOT_KEY });
const index = await admin.loadIndex({ indexName: 'documents' });

const { userId, apiKey } = await index.createUser({ permissions: ['read', 'write'] });
// capture apiKey once — never recoverable

admin, _ := cyborgdb.NewClient("http://localhost:8000", rootKey)
index, _ := admin.LoadIndex(context.Background(), "documents", nil)

user, _ := index.CreateUser(context.Background(), []string{"read", "write"})
// Hand user.APIKey to the new user via a secure channel — it is never recoverable.
// Avoid logging or printing it.
_ = user.UserID
_ = user.APIKey

The api_key is returned exactly once and is never stored by the service. If you lose it, you must revoke the user and mint a new one. Hand it to the user securely (out-of-band, encrypted channel, secret store).

The user authenticates by passing cdbk_… as api_key to their Client — they need no index key of their own (the service resolves the index KEK server-side).

# End user
from cyborgdb import Client

client = Client(base_url='http://localhost:8000', api_key='cdbk_…')
index = client.load_index('documents')  # no index_key argument
index.query(query_vectors=[0.1]*384, top_k=5)

Listing and revoking users

# List
curl -X GET "http://localhost:8000/v1/indexes/documents/users" \
     -H "X-API-Key: $CYBORGDB_SERVICE_ROOT_KEY"

# Revoke
curl -X DELETE "http://localhost:8000/v1/indexes/documents/users/ab12…" \
     -H "X-API-Key: $CYBORGDB_SERVICE_ROOT_KEY"

users = index.list_users()
for u in users:
    print(u['user_id'], u['permissions'])

index.delete_user('ab12…')  # cryptographic revocation

const users = await index.listUsers();
await index.deleteUser({ userId: 'ab12…' });

users, _ := index.ListUsers(context.Background())
_ = index.DeleteUser(context.Background(), "ab12…")

Revocation is cryptographic, not policy-based: the service erases that user’s wrapped DEK(s) for the index. On the next request, the service has nothing to unwrap for them — even a captured cdbk_… token becomes useless. There is no propagation lag.

KMS-backed constraint

Per-user keys work only against KMS-backed indexes — i.e., indexes created with kms_name=… rather than index_key=…. The reason is mechanical: a user does not hold the index key, so the service must be able to resolve it server-side from a kms.registry slot. For SDK-supplied indexes (provider: none), there is no server-side key to resolve, so per-user provisioning is not supported. If you want multi-tenant access to an index that today uses an SDK-supplied key, migrate it to KMS-backed first (see Managing Encryption Keys → Migrating).

Mint-time provisioning still requires the index KEK to bootstrap the new user’s wrapped DEK. For KMS-backed indexes this happens server-side; for SDK-supplied indexes you’d need to pass the index key on the create_user call, but the resulting user still wouldn’t have a path to authenticate (the service can’t resolve the KEK for their later requests). This is why the constraint exists end-to-end.

End-to-end example

A typical operator workflow for onboarding a new tenant:

Provision a KMS slot

Add a registry entry to your service YAML — see KMS & BYOK.

cyborgdb.yaml

kms:
  registry:
    tenant-acme:
      provider: aws-kms
      key_id:   alias/cyborgdb-acme
      region:   us-east-1

Restart the service. Look for KMS registry loaded in the logs.

Create the tenant's index (root)

curl -X POST "http://localhost:8000/v1/indexes/create" \
     -H "X-API-Key: $CYBORGDB_SERVICE_ROOT_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "acme-documents",
       "kms_name": "tenant-acme",
       "dimension": 384,
       "metric": "cosine"
     }'

Mint a user key for the tenant (root)

curl -X POST "http://localhost:8000/v1/indexes/acme-documents/users" \
     -H "X-API-Key: $CYBORGDB_SERVICE_ROOT_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "permissions": ["read", "write"] }'

Hand the returned cdbk_… to the tenant out-of-band.

Tenant uses the index

The tenant configures their SDK client with api_key = "cdbk_…" and operates only on acme-documents. They cannot list, describe, or touch any other tenant’s index.

Revoke when access ends

curl -X DELETE "http://localhost:8000/v1/indexes/acme-documents/users/<user_id>" \
     -H "X-API-Key: $CYBORGDB_SERVICE_ROOT_KEY"

Revocation is immediate — the tenant’s next request fails with 401.

Operational notes

Read vs write semantics. read covers query, get, list_ids, describe. write covers upsert, delete. Index lifecycle operations (create, train, delete_index) and user management are root-only — there’s no “delegated admin” permission.
KEK cache. Plaintext index KEKs live in an in-process cache for INDEX_KEK_CACHE_TTL_SECONDS (default 60s). Revoking a user is immediate and cryptographic; revoking KMS-level access to the wrap key propagates within the cache TTL.
Restarting the service. User keys survive restart — the wrapped DEKs are persisted alongside the index envelope. The root key is read from env/YAML on every start.
Auditing. The service logs the kind of key (root / user / legacy / none) on each request at INFO. Pair with structured logging to attribute index activity to users.

CyborgDB Service

Encrypted Indexes

Data Operations

Advanced

Modes

Key kinds

Provisioning users

Listing and revoking users

KMS-backed constraint

End-to-end example

Operational notes

See also

​Modes

​Key kinds

​Provisioning users

​Listing and revoking users

​KMS-backed constraint

​End-to-end example

​Operational notes

​See also

Modes

Key kinds

Provisioning users

Listing and revoking users

KMS-backed constraint

End-to-end example

Operational notes

See also