Audit log
What the workspace audit log records, who can read it, how to filter and export it, and its append-only guarantee. Business plan and above.
Every workspace on Business or Enterprise has an append-only log of what happened in it: who did what, to which document or setting, from which address, when.
What is recorded
Each event has an action name, an actor (an email address, system for background jobs, or scim:<workspace> for provisioning calls), a target_type and target_id, a meta object with the details that matter for that action (a document's title and folder, the old and new role, the keys a policy change touched), the client ip, and created_at.
The action families:
Documents: doc.publish, doc.update, doc.rename, doc.tags, doc.move, doc.description, doc.file_put, doc.file_delete, doc.edit, doc.patch, doc.restore, doc.alias, doc.delete.
Access and sharing: doc.visibility, doc.listing, doc.retention, doc.viewed (one event per view of a Restricted document, with the viewer's email as the actor), access.grant, access.revoke, comment.add, comment.resolve, comment.unresolve, comment.delete.
Roots, folders and agents: root.create, root.update, root.delete, folder.publish, folder.unpublish (changes to a root's or folder's access list use access.grant and access.revoke), brain.create, brain.write, brain.propose, brain.decide, brain.source, brain.includes, brain.access, brain.delete.
Members and groups: member.invite, member.invite_revoke, member.join (with how: invite, SSO or SCIM), member.leave, member.role, group.create, group.rename, group.delete, group.member_add, group.member_remove.
Sign-in and tokens: user.sign_in (Google and SSO, with the method), token.minted, token.revoked, sso.config, sso.delete, scim.token_create, scim.token_revoke.
Policy and compliance: policy.updated, policy.ip_denied, doc.secret_warning, doc.legal_hold, doc.legal_hold_released.
Webhooks: webhook.created, webhook.updated, webhook.deleted, webhook.test.
Account and operator actions: account.export, account.delete_requested, account.purged, and the operator actions admin.plan_set, admin.workspace_created, admin.user_moved, admin.user_disabled.
GET /api/audit/actions returns the names that exist, for building a filter.
Viewer analytics are available separately in File activity, including public links and verified workspace identities when available. Legacy doc.viewed audit rows follow the plan's detail retention and require permission to manage the file's sharing; they cannot be used to bypass Activity permissions.
Who can read it
- Workspace owners and admins see the whole workspace.
- Members see events about documents they own.
- Auditors can inspect workspace events and review managed Agent tool calls. File viewer activity retains its existing access restrictions; the role does not unlock private documents or another person's complete tool result.
A workspace below Business gets a 402 (the audit log requires the Business plan or above).
Reading it
GET /api/audit returns events newest first, 100 by default and up to 500 per call, with a next_before_id cursor for the next page. Filters, all optional and combinable:
| Parameter | Matches |
|---|---|
action |
one action name, such as doc.publish |
actor |
the actor string exactly, usually an email |
target_type |
doc, user, workspace, group, invite, webhook, folder, workflow, scim_token |
target_id |
one target, such as a document id |
from, to |
an ISO-8601 timestamp or a bare YYYY-MM-DD, inclusive |
before_id |
the cursor from the previous page |
From an agent, list_audit(action, limit) returns the same events (up to 200), scoped the same way. Prompt: "Who changed the visibility of the Acme proposal?" The agent calls list_audit with action: "doc.visibility" and reads meta.
Export
GET /api/audit/export.csv streams the log with the same filters as a CSV file named audit-log.csv, newest first, with the columns id, created_at, action, actor, target_type, target_id, ip, meta (meta is JSON). An export contains up to 100,000 rows; narrow the time range for more.
Append-only
No API lets a caller edit an audit event. Security and change records remain for the life of the workspace, including an actor's email after account deletion. Viewer records (doc.viewed) are an exception: scheduled cleanup removes them after the plan's activity detail window. Longer-lived, identity-free viewer totals are kept in the separate activity tables.
In the app
The Audit page includes Agent tool activity and Workspace events. Filter tool calls by Agent, connection, person, tool or stated intent. Use Awaiting approval, Review recommended, and Blocked / needs attention to find calls needing a decision. This preview has not yet been deployed.
For an approval-required request, an authorized admin or Auditor reads the proposed action and linked account, adds a review reason, then chooses Approve exact action or Reject. Approval leaves execution to the original requester; it does not dispatch the tool automatically. Workspace policy can require a different approver.
Mark reviewed acknowledges an allowed action's review flag; it does not undo an action or approve one retroactively. Unknown means the upstream provider may have completed an interrupted action, so reconcile there before requesting a retry.
The detail view separates the supplied intent, AI use-case assessment, policy outcome and review note. These are observable records and concise explanations, not raw hidden model reasoning. Read the MCP reference for submitting actions and checking their status from an agent.