TracecatHQ · topher-lo · Aug 3, 2026 · Jul 31, 2026 · Jul 31, 2026 · Jul 31, 2026
diff --git a/docs/agents/secrets-variables.mdx b/docs/agents/secrets-variables.mdx
@@ -15,7 +15,7 @@ Preset agent tool calls go through a secure server-side proxy.
 The LLM only sees the raw expression placeholder (e.g. `${{ SECRETS.threatintel.API_KEY }}`). The actual secret values are injected server-side at the tool execution layer after the model responds, so the LLM never has access to your credentials.
 
 <Warning>
-`ai.action` and `ai.agent` actions do **not** support secure secrets injection. Secret and variable expressions are evaluated immediately in workflow action inputs and will be exposed to the LLM.
+Do not use `SECRETS` expressions — or any expression that resolves to a value you would not send to your LLM provider — in `ai.action` or `ai.agent` inputs. Use `ai.preset_agent` for secure secrets injection.
 </Warning>
 
 ## Secrets

diff --git a/docs/audit-logs/agents.mdx b/docs/audit-logs/agents.mdx
@@ -0,0 +1,14 @@
+---
+title: "Organization agent logs"
+description: "Export OpenTelemetry metrics, log events, and traces for agent runs to your observability backend."
+---
+
+This page is a work in progress.
+
+Agent runs export OpenTelemetry signals to your observability backend. Configure the exporter under Organization settings, then open **Agent OTel**.
+
+## Related pages
+
+- See [Organization audit logs](/audit-logs/organization) to stream user and service-account activity to your SIEM.
+- See [Platform audit logs](/audit-logs/platform) to capture administration above the organization boundary.
+- See [Architecture](/security/architecture) for the sandbox and gateway boundaries that agent telemetry crosses.
diff --git a/docs/audit-logs/mcp-access.mdx b/docs/audit-logs/mcp-access.mdx
@@ -0,0 +1,14 @@
+---
+title: "MCP access logs"
+description: "Review OAuth connections, personal access tokens, and external MCP client activity in a workspace."
+---
+
+This page is a work in progress.
+
+External MCP clients connect to Tracecat and call tools as a real user. Review their connections, tokens, and activity from the workspace sidebar under **MCP access**.
+
+## Related pages
+
+- See [Organization audit logs](/audit-logs/organization) to stream token issuance and revocation to your SIEM.
+- See [Platform audit logs](/audit-logs/platform) to capture administration above the organization boundary.
+- See [Architecture](/security/architecture) for the permission model behind MCP connections.
diff --git a/docs/audit-logs/organization.mdx b/docs/audit-logs/organization.mdx
@@ -1,12 +1,20 @@
 ---
 title: "Organization audit logs"
 description: "Stream organization audit events to an HTTPS webhook and shape each request for your log collector."
+keywords: ["organization audit", "audit webhook", "SIEM"]
 ---
 
+import AuditDeliveryBehavior from "/snippets/audit-delivery-behavior.mdx";
+import AuditEventFields from "/snippets/audit-event-fields.mdx";
+import AuditRequestOptions from "/snippets/audit-request-options.mdx";
+
 Send organization audit events to an external log collector over HTTPS.
 You must be an organization administrator to configure the endpoint.
 
-## Connect a log collector
+Each event answers one question: which identity changed which resource, from where, and did it work.
+The stream covers privilege changes, credential changes, agent configuration changes, and automation changes.
+
+## Configure audit logs
 
 <Steps>
   <Step title="Open organization settings">
@@ -21,28 +29,120 @@ You must be an organization administrator to configure the endpoint.
     </Frame>
   </Step>
   <Step title="Configure the request">
-    Add any headers your collector requires. You can also merge custom JSON into
-    every event, wrap the payload under a key such as `event`, and control TLS
-    certificate verification.
-  </Step>
-  <Step title="Save and verify delivery">
-    Click **Save changes**, then confirm that your collector receives an
-    `organization_setting` event with a `SUCCESS` status.
+    Set the request options your collector needs, then click **Save changes**.
   </Step>
 </Steps>
 
-## Request options
+Changing the endpoint is itself an audited `organization_setting` update, so your existing collector records the change before the stream moves.
+Events can continue to reach the old endpoint for up to 30 seconds after the change while cached settings expire.
 
-| Option | Behavior |
-| --- | --- |
-| Audit webhook URL | Receives each event as a JSON `POST` request. |
-| Custom headers | Adds static headers to every request. Header names are case-insensitive. |
-| Custom payload | Merges a JSON object into every event. Custom keys replace matching default keys. |
-| Payload attribute | Wraps the complete payload under the configured key. |
-| Verify SSL certificate | Verifies the endpoint certificate. Disable this only for a trusted endpoint that uses a private or self-signed certificate. |
+## Request options
 
-Tracecat encrypts the webhook URL, custom headers, and custom payload at rest.
-Choose custom payload keys that do not overlap default fields unless you intend to replace them.
+<AuditRequestOptions />
+
+## Logged events
+
+| Resource type | Action | Description |
+| --- | --- | --- |
+| `agent_catalog` | `create` | A model was added to the organization's agent catalog. |
+| `agent_catalog` | `delete` | A model was removed from the organization's agent catalog. |
+| `agent_catalog` | `update` | An agent catalog entry was updated. |
+| `agent_custom_provider` | `create` | A custom model provider was configured. |
+| `agent_custom_provider` | `delete` | A custom model provider was removed. |
+| `agent_custom_provider` | `update` | A custom model provider was reconfigured. |
+| `agent_model_access` | `create` | A catalog model was enabled for an organization or workspace. |
+| `agent_model_access` | `delete` | A catalog model was disabled for an organization or workspace. |
+| `agent_preset` | `create` | An agent preset was created. |
+| `agent_preset` | `delete` | An agent preset was deleted. |
+| `agent_preset` | `update` | An agent preset was updated or restored to an earlier version. |
+| `agent_session` | `delete` | An agent session and its history were deleted. |
+| `agent_session` | `update` | An agent session's title, preset, or MCP integrations changed. |
+| `auth` | `sign_in` | A user signed in. |
+| `case` | `create` | A case was created. |
+| `case` | `delete` | A case was deleted. |
+| `case` | `update` | A case was updated. |
+| `case_comment` | `create` | A comment was added to a case. |
+| `case_comment` | `delete` | A case comment was deleted. |
+| `case_comment` | `update` | A case comment was edited. |
+| `case_trigger` | `update` | Part of a workflow's case trigger configuration changed. |
+| `case_trigger` | `upsert` | A workflow's case trigger configuration was created or replaced. |
+| `mcp_personal_access_token` | `create` | An MCP personal access token was issued. |
+| `mcp_personal_access_token` | `revoke` | An MCP personal access token was revoked. |
+| `organization` | `delete` | An organization was deleted. |
+| `organization_invitation` | `accept` | An organization invitation was accepted. |
+| `organization_invitation` | `create` | An organization invitation was sent. |
+| `organization_invitation` | `revoke` | An organization invitation was revoked. |
+| `organization_member` | `create` | A user was added to the organization. |
+| `organization_member` | `delete` | A user was removed from the organization. |
+| `organization_member` | `update` | An organization member's details changed. |
+| `organization_secret` | `create` | An organization secret was created. |
+| `organization_secret` | `delete` | An organization secret was deleted. |
+| `organization_secret` | `update` | An organization secret was updated. |
+| `organization_session` | `delete` | A member's active login session was revoked. |
+| `organization_setting` | `create` | An organization setting was created. |
+| `organization_setting` | `delete` | An organization setting was deleted. |
+| `organization_setting` | `update` | An organization setting changed, including this audit sink. |
+| `rbac_assignment` | `create` | A role was assigned to a group. |
+| `rbac_assignment` | `delete` | A group's role assignment was removed. |
+| `rbac_assignment` | `update` | A group's role assignment changed. |
+| `rbac_group` | `create` | A group was created. |
+| `rbac_group` | `delete` | A group was deleted. |
+| `rbac_group` | `update` | A group was updated. |
+| `rbac_group_member` | `create` | A user was added to a group. |
+| `rbac_group_member` | `delete` | A user was removed from a group. |
+| `rbac_role` | `create` | A custom role was created. |
+| `rbac_role` | `delete` | A custom role was deleted. |
+| `rbac_role` | `update` | A role's scopes changed. |
+| `rbac_scope` | `create` | A custom permission scope was created. |
+| `rbac_scope` | `delete` | A custom permission scope was deleted. |
+| `rbac_user_assignment` | `create` | A role was assigned directly to a user. |
+| `rbac_user_assignment` | `delete` | A user's role assignment was removed. |
+| `rbac_user_assignment` | `update` | A user's role assignment changed. |
+| `schedule` | `create` | A workflow schedule was created. |
+| `schedule` | `delete` | A workflow schedule was deleted. |
+| `schedule` | `update` | A workflow schedule was updated. |
+| `secret` | `create` | A workspace secret was created. |
+| `secret` | `delete` | A workspace secret was deleted. |
+| `secret` | `update` | A workspace secret was updated. |
+| `service_account` | `create` | A service account was created. |
+| `service_account` | `update` | A service account was renamed, re-scoped, disabled, or enabled. |
+| `service_account_api_key` | `create` | An API key was issued for a service account. |
+| `service_account_api_key` | `revoke` | A service account API key was revoked. |
+| `table` | `create` | A lookup table was created. |
+| `table` | `delete` | A lookup table was deleted. |
+| `table` | `update` | A lookup table was updated. |
+| `table_column` | `create` | A column was added to a lookup table. |
+| `table_column` | `delete` | A column was removed from a lookup table. |
+| `table_column` | `update` | A lookup table column was updated. |
+| `tag` | `create` | A workflow tag was created. |
+| `tag` | `delete` | A workflow tag was deleted. |
+| `tag` | `update` | A workflow tag was updated. |
+| `webhook` | `create` | A workflow webhook trigger was created. |
+| `webhook` | `update` | A workflow webhook trigger was updated. |
+| `webhook_api_key` | `create` | The first API key was issued for a webhook. |
+| `webhook_api_key` | `delete` | A webhook API key was deleted. |
+| `webhook_api_key` | `revoke` | A webhook API key was revoked and kept on record. |
+| `webhook_api_key` | `rotate` | An existing webhook API key was replaced. |
+| `workflow` | `create` | A workflow was created. |
+| `workflow` | `delete` | A workflow was deleted. |
+| `workflow` | `publish` | A workflow definition was published. |
+| `workflow` | `update` | A workflow was updated. |
+| `workflow_execution` | `cancel` | A workflow execution was cancelled and allowed to clean up. |
+| `workflow_execution` | `create` | A workflow execution was started. |
+| `workflow_execution` | `reset` | A workflow execution was replayed from an earlier event. |
+| `workflow_execution` | `terminate` | A workflow execution was stopped immediately. |
+| `workspace` | `create` | A workspace was created. |
+| `workspace` | `delete` | A workspace was deleted. |
+| `workspace` | `update` | A workspace was updated. |
+| `workspace_invitation` | `accept` | A workspace invitation was accepted. |
+| `workspace_invitation` | `create` | A workspace invitation was sent. |
+| `workspace_invitation` | `revoke` | A workspace invitation was revoked. |
+| `workspace_variable` | `create` | A workspace variable was created. |
+| `workspace_variable` | `delete` | A workspace variable was deleted. |
+| `workspace_variable` | `update` | A workspace variable was updated. |
+
+An organization-scoped sign-in emits `auth` `sign_in` to this sink and to the platform sink.
+A superuser login that carries no organization context reaches the platform sink only.
 
 ## Event payload
 
@@ -56,39 +156,48 @@ An audit event contains the actor, affected resource, action, result, and scope.
   "actor_id": "00000000-0000-4000-8000-000000000003",
   "actor_label": "avery@example.com",
   "ip_address": "192.0.2.10",
+  "user_agent": "Mozilla/5.0",
   "resource_type": "workflow",
   "resource_id": "00000000-0000-4000-8000-000000000004",
   "action": "update",
   "status": "SUCCESS",
-  "data": null,
+  "data": {
+    "changed_fields": ["title"]
+  },
   "created_at": "2026-01-15T14:03:12.123456Z"
 }
 ```
 
-| Field | Description |
-| --- | --- |
-| `organization_id` | Organization that owns the event. |
-| `workspace_id` | Workspace that owns the resource, when applicable. |
-| `actor_type` | `USER` or `SERVICE_ACCOUNT`. |
-| `actor_id` | ID of the user or service account that performed the action. |
-| `actor_label` | User email or service account name, when available. |
-| `ip_address` | Source IP address, when available. |
-| `resource_type` | Type of resource affected by the action. |
-| `resource_id` | ID of the affected resource, when available. |
-| `action` | Operation performed on the resource. |
-| `status` | `ATTEMPT`, `SUCCESS`, or `FAILURE`. |
-| `data` | Additional event-specific context, when available. |
-| `created_at` | UTC timestamp for the event. |
+<AuditEventFields />
+
+### Attribution
+
+`actor_type` distinguishes a human from automation.
+`USER` events carry the account's email in `actor_label`, and `SERVICE_ACCOUNT` events carry the service account's name.
+
+Treat `actor_id` as the stable join key; `actor_label` is a display value that changes when a user's email changes.
+
+### Scope
+
+`organization_id` identifies the tenant and `workspace_id` identifies the workspace that owns the affected resource.
+Organization-level resources such as `organization_member` and `rbac_role` have no workspace, so `workspace_id` is `null`.
+
+If you index platform and organization events together, filter on `organization_id` being non-null to isolate tenant activity.
+
+### Status lifecycle
 
 Most audited changes emit an `ATTEMPT` event followed by `SUCCESS` or `FAILURE`.
-Your endpoint should return a successful response within 10 seconds; delivery failures do not block the audited action.
 
-## Update or disconnect the endpoint
+An `ATTEMPT` with no matching terminal event does not always mean the request failed — the terminal event may have been shed or lost in delivery.
+
+## Delivery behavior
 
-Return to **Organization → Audit Logs** to update the request settings.
-Click the disconnect button to stop sending new organization audit events.
+<AuditDeliveryBehavior />
 
 ## Related pages
 
-- See [Security architecture](/security/architecture) for the platform, agent, approval, and telemetry boundaries around audit events.
+- See [Platform audit logs](/audit-logs/platform) to capture administration above the organization boundary.
+- See [Organization agent logs](/audit-logs/agents) to export telemetry for agent runs.
+- See [MCP access logs](/audit-logs/mcp-access) to review external MCP clients acting as your users.
+- See [Architecture](/security/architecture) for the platform, agent, approval, and telemetry boundaries around audit events.
 - See [Security](/self-hosting/security) for deployment hardening guidance.