Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.chatblocks.ai/llms.txt

Use this file to discover all available pages before exploring further.

The audit log is a customer-visible append-only record of every privileged action on your workspace. It’s the trust boundary on top of MCP keys and BYOK credentials: if something modified your blocks, decrypted your data-source credentials, or ran your scheduled agent, it left a row.

​
What gets logged

Writes only. Reads are intentionally not audited — the read trust boundary is the MCP-key auth check, not per-row logging. Logged actions include:
  • Connector credential decrypts — every time a refresh, test-connection, or schema introspection decrypts a data-source credential, with the calling actor.
  • BYOK key decrypts — each time the scheduled runner or schedule-preview pulls a plaintext Anthropic / OpenAI / Google key out of envelope encryption.
  • MCP write tool calls — blocks.update, blocks.setWidgetData, blocks.publish, blocks.delete, the placement writes, dataSources.add / delete / editRefreshPolicy, schedule.set / pause / resume / delete / runNow, byokKeys.add / delete.
  • Schedule previews — the streaming schedule.preview MCP tool stamps an audit row with targetId set to the BYOK key id it used.
  • Member invites and role changes — workspace admin actions on workspaceMembers and workspaceInvites.
Things that are deliberately not logged:
  • MCP read tools (blocks.list, canvases.get, auditLog.recent, workspace.get, etc.).
  • BYOK key list (byokKeys.list) — listing metadata doesn’t decrypt anything.
  • Web UI navigation and public canvas views.

​
Row shape

Each row carries:
  • workspaceId — the workspace the action targeted.
  • actor — who, in a structured string:
    • "user:<authUserId>" — a human acting through the web UI.
    • "mcp:<apiKeyId>" — an MCP call authenticated by a cb_live_* key.
    • "system:scheduledRunner" — the Trigger.dev runner decrypting credentials for a scheduled agent run.
    • "system:schedulePreview" — the streaming preview tool’s ephemeral decrypt path.
    • "system:byok" — generic BYOK substrate operations.
  • action — what, as a dotted verb:
    • "mcp.<toolName>" for every MCP write (mcp.blocks.publish, mcp.schedule.set, etc.).
    • "byok.decrypt" for BYOK plaintext reads.
    • "datasource.decrypt" for connector credential reads.
    • "member.invite", "member.role" for workspace membership changes.
  • targetId — the resource id this action acted on (block id, schedule id, BYOK key id, data source id, etc.). Nullable for actions without a single target.
  • createdAt — ISO timestamp.
  • metadata — optional structured detail (e.g. the error message on a failed decrypt).

​
How to query

Any coding agent connected to the workspace can call:
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "auditLog.recent",
    "arguments": { "limit": 50 }
  }
}
limit defaults to 50 and caps at 200. Returns rows newest-first. See the MCP tool reference for the full schema.

​
Retention

Audit rows are retained indefinitely in v1. There’s no automatic pruning. A future retention policy (e.g. 90 days on Free, 365 days on Builder, indefinite on Enterprise) is on the roadmap but not committed; if you need a guarantee, contact us.
When you’re debugging “why did this block change,” start with auditLog.recent filtered to that block’s id (client-side filter on the targetId field). The actor will tell you whether it was you in the web UI, an MCP key, or the scheduled runner — and the action tells you which tool ran.

​
What’s next

MCP tool reference

The full schema for auditLog.recent and every other MCP tool.

BYOK keys

How BYOK envelope encryption works, what gets logged on decrypt, and how the runner uses them.