API Keys

divinci.apiKeys manages the API keys that authenticate access to a workspace. Keys are workspace-scoped, so every call takes a workspaceId.

Creating a key

The secret is returned once, at creation. Store it immediately.

const created = await divinci.apiKeys.create({
  workspaceId: "ws_123",
  name: "CI pipeline",
  // optional: permissions, expiry, etc.
});

console.log(created.secret); // shown only here — save it now

Danger

The raw secret is only present on the create and rotate responses. It is never returned again. If you lose it, rotate the key.

Permissions & scopes

permissions controls what a key may do. Leave it empty (or omit it) and the key gets full access scoped to its workspace — the right default for a trusted backend integration. Pass an explicit array only when you want to restrict the key:

// Full access (scoped to the workspace) — empty/omitted permissions
const full = await divinci.apiKeys.create({ workspaceId: "ws_123", name: "backend" });

// Restricted: this key can read RAG and send chat messages, nothing else
const scoped = await divinci.apiKeys.create({
  workspaceId: "ws_123",
  name: "chat widget",
  permissions: ["rag:read", "transcript:write"],
});

Each scope is category:action:

Scope	Grants
transcript:read / transcript:write	Read transcripts / send chat messages
rag:read / rag:write	Read / manage RAG vectors and sources
release:read / release:write	Read / manage releases
finetune:read / finetune:write	Read / manage fine-tune jobs
whitelabel:read / whitelabel:write	Read / modify workspace config
analytics:read	Read usage analytics
byok:read / byok:write / byok:resolve	Manage bring-your-own provider keys

Chat needs transcript:write

There is no separate “chat” scope — chat is gated by transcript:write. A key with an explicit permissions array that omits it will get 403 on chat calls (chat.create / chat.send). If you only need chat to work, the simplest path is to leave permissions empty (full access) and tighten later — an empty-permissions key already permits chat.

Listing, reading, updating

const { data } = await divinci.apiKeys.list("ws_123", { limit: 20 });
const key = await divinci.apiKeys.get("ws_123", "key_abc");
await divinci.apiKeys.update("ws_123", "key_abc", { name: "CI pipeline (prod)" });

Rotating and revoking

// Rotate: issues a new secret, invalidates the old one
const rotated = await divinci.apiKeys.rotate("ws_123", "key_abc");
console.log(rotated.secret);

// Revoke: disable without deleting the record
await divinci.apiKeys.revoke("ws_123", "key_abc");

// Delete entirely
await divinci.apiKeys.delete("ws_123", "key_abc");

Validating a key

Check a key’s status without making an authenticated call:

const result = await divinci.apiKeys.validate("divinci_key_...");

if (result.valid) {
  console.log(result.status);       // "active" | "revoked" | "expired"
  console.log(result.workspaceId);
  console.log(result.permissions);
} else {
  console.error(result.error);
}

Usage stats

const usage = await divinci.apiKeys.getUsage("ws_123", "key_abc", "month");

Method reference

Method	Description
list(workspaceId, options?)	Paginated keys.
get(workspaceId, keyId)	Fetch a key (no secret).
create(options)	Create a key; returns the secret once.
update(workspaceId, keyId, options)	Update key metadata.
rotate(workspaceId, keyId)	Issue a new secret, invalidate the old.
revoke(workspaceId, keyId)	Disable a key.
delete(workspaceId, keyId)	Permanently delete a key.
validate(apiKey)	Check status, workspace, and permissions.
getUsage(workspaceId, keyId, period?)	Usage stats.