User Management (RBAC)

When the service runs with CYBORGDB_SERVICE_ROOT_KEY set, EncryptedIndex can create, list, and revoke per-index users. These methods require a client created with the root key.

See Multi-Tenancy & RBAC for the operator-side playbook (modes, key kinds, SDK-supplied indexes).

createUser

Creates a user scoped to this index and returns their API key.

async createUser({ permissions: string[] }): Promise<{ userId: string; apiKey: string }>

Parameters

Parameter	Type	Description
`permissions`	`string[]`	Non-empty subset of `['read', 'write']`.

Returns

Promise<{ userId, apiKey }>:

Field	Type	Description
`userId`	`string`	Hex identifier for the new user.
`apiKey`	`string`	The user’s API key, starting with `cdbk_`.

The service returns apiKey only in this response and never stores it. Give it to the user over a secure channel and don’t log it. If it’s lost, delete the user and create a new one.

Example

import { Client } from 'cyborgdb';

const ROOT_KEY = 'your-service-root-key';
const indexKey = new Uint8Array(Buffer.from('your-64-character-hex-key', 'hex'));

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

const user = await index.createUser({ permissions: ['read', 'write'] });
console.log(Object.keys(user).sort());
// Output: [ 'apiKey', 'userId' ]

// The user connects with their own key
const userClient = new Client({ baseUrl: 'http://localhost:8000', apiKey: user.apiKey });

listUsers

Lists the users created for this index.

async listUsers(): Promise<{ userId: string; permissions: string[] }[]>

Returns

An array of { userId, permissions }, where permissions is a subset of ['read', 'write'].

Example

await index.createUser({ permissions: ['read'] });

for (const u of await index.listUsers()) {
    console.log(u.permissions);
}
// Output: [ 'read' ]

Deleting an index doesn’t delete its user records. If you create a new index with the same name, listUsers() on it still returns the old users. They can’t read the new index, because their keys don’t unwrap its data key; delete them with deleteUser().

deleteUser

Revokes a user. Their access keys for this index are erased, so their cdbk_ key stops working on the next request.

async deleteUser({ userId: string }): Promise<void>

Parameters

Parameter	Type	Description
`userId`	`string`	`userId` from `createUser()` or `listUsers()`.

Example

const { userId } = await index.createUser({ permissions: ['read'] });
await index.deleteUser({ userId });

console.log(await index.listUsers());
// Output: []

Exceptions

These apply to all three methods:

CyborgDBAuthenticationError

The client isn’t using the root key (HTTP 403), or its apiKey is invalid (HTTP 401).

CyborgDBValidationError

permissions is empty or contains a value other than 'read' or 'write', or userId isn’t hex (HTTP 400).

CyborgDBNotFoundError

The index doesn’t exist (HTTP 404).

CyborgDBServiceError

The service returns 5xx.

See Errors for the full hierarchy.

Introduction

Client

Encrypted Index

Types & Helpers

createUser

Parameters

Returns

Example

listUsers

Returns

Example

deleteUser

Parameters

Example

Exceptions

​createUser

​Parameters

​Returns

​Example

​listUsers

​Returns

​Example

​deleteUser

​Parameters

​Example

​Exceptions

createUser

Parameters

Returns

Example

listUsers

Returns

Example

deleteUser

Parameters

Example

Exceptions