> This page is for Workforce. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Audit trail > What the Workforce audit trail records: the event catalog across tool access, models, and security, the fields on each entry, how updates render a diff, CSV export, and retention. The audit trail is an append-only record of every privileged action taken in your Workforce organization: members invited, roles changed, API keys rotated, Groups remapped, security rules edited, routing policies changed, skills published, plus the handful of reads worth recording on their own, such as a log search. It is the artifact your security review asks for, and the evidence you pull when you need to know who changed what and when. It is not activity. What an employee's AI client did lives in [Tool call logs](/merge-workforce/logs/tool-calls) and [LLM calls](/merge-workforce/logs/gateway); model requests and tool calls are never audit events. The audit trail is administrative change. Open [Settings → Audit trail](https://wf-develop.merge.dev/settings/audit-trail). Reading and exporting it needs the View audit trail permission. The filter bar takes three things: date (before, after, or between), event type, and the user who acted. Filters are held in the URL, so a filtered view is a link you can send someone. Click a row for the event detail and, on updates, the full field-level diff. ## What's captured Each entry stores a snapshot of the actor and the target, denormalized at write time, so the row stays readable after the user, role, or resource it names has been deleted. | Field | What it holds | | -------------------------- | --------------------------------------------------------------------------------------------------------------- | | `event_type` | What was done, such as `ROLE_UPDATED` or `SECURITY_RULE_UPDATED` | | `event_description` | A human-readable summary, with a change summary on updates | | `created_at` | When the event was recorded, UTC with timezone | | `user_name` / `user_email` | The dashboard member who acted, or empty for system-driven events such as SCIM | | `role_name` | Their role at the moment of the event, surviving a later rename | | Resource type and ID | What was changed: employee, Group, Tool Pack, rule, routing policy, member | | Source | Web dashboard, API, or system | | `ip_address` | The actor's IP, from `CF-Connecting-IP` when present, otherwise the request socket | | `url` / `method` | The HTTP path and verb behind the action | | `request_body` | The validated request body, for handlers that are not auth-adjacent. See [Sensitive fields](#sensitive-fields). | The table is append-only. Entries are never modified after they are written, and nothing can be backfilled: an event is emitted inside the transaction that performs the mutation, or not at all. Failed actions mostly write nothing, because the mutation never began, with the exception of `LOGIN_FAILED` and `MFA_VERIFICATION_FAILED`. ## Event catalog Event types are uppercase strings, and the same value works as an `?event_type=` filter on the audit-log endpoint. The authoritative list is the `event_type` enum on the [audit-log endpoint](/merge-agent-handler/agent-handler/audit-log) in the API reference: it is generated from the source and picks up new values as features ship, so read it there before you hard-code a filter. The dashboard's event-type dropdown is generated from the same source, and the newest event types can land in the record before they reach the dropdown, so filter on the endpoint when the dropdown does not offer the one you want. | Area | Event | Fires when | | -------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Sign-in and MFA | `LOGIN_SUCCESS` / `LOGIN_FAILED` / `LOGOUT` | A dashboard sign-in succeeds or fails, or a member signs out | | Sign-in and MFA | `MFA_ENABLED` / `MFA_DISABLED` / `MFA_DEVICE_CHANGED` | A member turns MFA on, turns it off, or re-enrolls an authenticator | | Sign-in and MFA | `MFA_VERIFICATION_FAILED` | An MFA code is rejected at sign-in | | Sign-in and MFA | `MFA_ADMIN_RESET` | An admin clears a member's MFA enrollment | | Sign-in and MFA | `MFA_REQUIRED_ENABLED` / `MFA_REQUIRED_DISABLED` | The organization starts or stops requiring MFA | | Members and roles | `USER_INVITED` / `USER_INVITATION_ACCEPTED` / `USER_INVITATION_CANCELLED` | Invitation lifecycle for a dashboard member | | Members and roles | `USER_CREATED` / `USER_UPDATED` | A member is added, or their details or role change | | Members and roles | `USER_ENABLED` / `USER_DISABLED` | A member's dashboard access is restored or suspended | | Members and roles | `USER_PASSWORD_RESET` | A member's password is reset | | Members and roles | `ROLE_CREATED` / `ROLE_UPDATED` / `ROLE_DELETED` | Custom role lifecycle | | Single sign-on | `SSO_PROVIDER_CREATED` / `SSO_PROVIDER_UPDATED` / `SSO_PROVIDER_DELETED` | An identity provider connection is configured, edited, or removed | | Single sign-on | `SSO_LOGIN_REQUIRED_ON` / `SSO_LOGIN_REQUIRED_OFF` | Whether members must sign in through the identity provider is turned on or off | | SCIM provisioning | `SCIM_TOKEN_CREATED` / `SCIM_TOKEN_REVOKED` | The SCIM bearer token is generated or revoked | | SCIM provisioning | `SCIM_USER_PROVISIONED` / `SCIM_USER_UPDATED` / `SCIM_USER_REACTIVATED` / `SCIM_USER_DEPROVISIONED` | Your identity provider creates, updates, reactivates, or deactivates an employee | | SCIM provisioning | `SCIM_USER_ACCESS_UPDATED` | One employee's tool access changes | | SCIM provisioning | `SCIM_GROUP_CREATED` / `SCIM_GROUP_UPDATED` / `SCIM_GROUP_DELETED` | Group lifecycle from the identity provider | | SCIM provisioning | `SCIM_GROUP_ACCESS_UPDATED` | A Group's tool access changes | | SCIM provisioning | `SCIM_DEFAULT_ACCESS_UPDATED` | The default access for an employee whose Group has no mapping changes | | Access requests | `SCIM_TOOL_ACCESS_REQUEST_CREATED` | An employee requests a tool they do not have | | Access requests | `SCIM_TOOL_ACCESS_REQUEST_APPROVED` / `SCIM_TOOL_ACCESS_REQUEST_DENIED` | A reviewer approves or denies a request | | Access requests | `SCIM_TOOL_ACCESS_REQUEST_REVOKED` / `SCIM_TOOL_ACCESS_REQUEST_CANCELED` | An approved grant is withdrawn, or the requester cancels | | Keys and tokens | `PRODUCTION_API_KEY_CREATED` / `PRODUCTION_API_KEY_REVOKED` / `PRODUCTION_API_KEY_REGENERATED` | A production key is created, revoked, or regenerated in place, which is how it rotates | | Keys and tokens | `TEST_API_KEY_CREATED` / `TEST_API_KEY_REGENERATED` / `TEST_API_KEY_REVOKED` / `TEST_API_KEY_DELETED` | Test key lifecycle | | Keys and tokens | `PERSONAL_ACCESS_TOKEN_GENERATED` / `PERSONAL_ACCESS_TOKEN_ROTATED` / `PERSONAL_ACCESS_TOKEN_REVOKED` | A member's own token for the CLI and the API is issued, rotated, or revoked | | Connectors | `CONNECTOR_IMPORTED` / `CONNECTOR_UPDATED` / `CONNECTOR_DELETED` | A [custom MCP server](/merge-workforce/connectors/custom-mcp-servers) is registered as a Connector, edited, or removed | | Connectors | `CONNECTOR_AUTH_SCOPE_RULE_CREATED` / `CONNECTOR_AUTH_SCOPE_RULE_UPDATED` / `CONNECTOR_AUTH_SCOPE_RULE_DELETED` | An OAuth scope override on a Connector changes | | Connectors | `APPLICATION_CREDENTIAL_CREATED` / `APPLICATION_CREDENTIAL_UPDATED` / `APPLICATION_CREDENTIAL_DELETED` | Your own OAuth app for a Connector is added, edited, or removed | | Employee connections | `CREDENTIAL_CREATED` / `CREDENTIAL_UPDATED` / `CREDENTIAL_DELETED` | An employee's connection to a Connector is stored, changed, or revoked | | Employee connections | `WORKFORCE_CREDENTIAL_UPSERTED` / `WORKFORCE_CREDENTIAL_DELETED` | The same, when the change came through the Workforce console | | Employees | `REGISTERED_USER_CREATED` / `REGISTERED_USER_UPDATED` / `REGISTERED_USER_DELETED` | An employee record is created, changed, or deleted | | Tool Packs | `TOOL_PACK_CREATED` / `TOOL_PACK_UPDATED` / `TOOL_PACK_DELETED` | Tool Pack lifecycle and configuration changes | | Security rules | `SECURITY_RULE_CREATED` / `SECURITY_RULE_UPDATED` / `SECURITY_RULE_DELETED` | A [Security Gateway](/merge-workforce/security/overview) rule or per-Tool-Pack override is created, edited, or deleted | | Model access | `WORKFORCE_BLOCKLIST_RULE_CREATED` / `WORKFORCE_BLOCKLIST_RULE_UPDATED` / `WORKFORCE_BLOCKLIST_RULE_DELETED` | A [model blocklist](/merge-workforce/models/access) rule changes | | Routing | `WORKFORCE_ROUTING_POLICY_CREATED` / `WORKFORCE_ROUTING_POLICY_UPDATED` / `WORKFORCE_ROUTING_POLICY_DELETED` | [Routing](/merge-workforce/models/routing) policy lifecycle | | Routing | `WORKFORCE_GROUP_ROUTING_UPDATED` / `WORKFORCE_EMPLOYEE_ROUTING_UPDATED` | A Group's or one employee's routing assignment changes | | Models | `WORKFORCE_MODEL_CONTROLS_UPDATED` / `WORKFORCE_MODEL_COMPRESSION_UPDATED` / `WORKFORCE_GROUP_MODELS_UPDATED` | Model controls, compression, or a Group's model access changes | | Models | `WORKFORCE_MODEL_MIGRATION_CREATED` / `WORKFORCE_MODEL_MIGRATION_UPDATED` | A model migration is created or moves through its lifecycle | | Budget | `WORKFORCE_GROUP_BUDGET_UPDATED` | A Group's [budget](/merge-workforce/models/budget) changes | | Employee keys | `WORKFORCE_EMPLOYEE_KEY_REVEALED` / `WORKFORCE_EMPLOYEE_KEY_ROTATED` | An employee's Gateway key is shown or rotated | | Evals | `EVAL_RUN_STARTED` | An eval run is triggered | | Skills | `SKILL_DRAFTED` / `SKILL_SUBMITTED` | A skill is saved as a draft, or submitted for review | | Skills | `SKILL_APPROVED` / `SKILL_REJECTED` | An admin approves or rejects a submission | | Skills | `SKILL_PUBLISHED` / `SKILL_UNPUBLISHED` / `SKILL_REPUBLISHED` | A skill or version is published, hidden from agents, or brought back | | Skills | `SKILL_ENABLED` / `SKILL_DISABLED` / `SKILL_DELETED` | A Merge-provided skill is turned on or off for the organization, or a skill is deleted | | Skills | `SKILL_EDITED` | A published skill is edited | | Skills | `SKILL_RETRIEVED` | An agent loads a skill with `retrieve_skill` | | Knowledge | `SYNCED_KNOWLEDGE_SOURCE_CONNECTED` / `SYNCED_KNOWLEDGE_SOURCE_DISCONNECTED` | A synced knowledge source is connected or disconnected | | Insights | `INSIGHT_ACTION_EXECUTED` / `INSIGHT_ACTION_DISMISSED` | An [Insights](/merge-workforce/insights) finding's action is applied or dismissed | | Desktop client | `DESKTOP_DEVICE_ENROLLED` / `DESKTOP_DEVICE_RE_ENROLLED` | A device enrolls with the [Workforce desktop client](/merge-workforce/devices/overview), or enrolls again | | Desktop client | `DESKTOP_DEVICE_IDENTITY_RESOLVED` | A device is matched to an employee | | Desktop client | `DESKTOP_PANEL_CONFIGURED` | The client's panel configuration changes | | Desktop client | `DESKTOP_TOOL_AUTH_STARTED` | An employee starts authenticating a Connector from the desktop client | | Desktop client | `DESKTOP_GATEWAY_CREDENTIAL_ISSUED` | An employee mints a per-device Gateway key from the menu bar | | Desktop client | `DESKTOP_ENROLLMENT_TOKEN_CREATED` / `DESKTOP_ENROLLMENT_TOKEN_REVOKED` | An admin mints or revokes an organization enrollment token | | Webhooks | `OUTBOUND_WEBHOOK_CREATED` / `OUTBOUND_WEBHOOK_UPDATED` / `OUTBOUND_WEBHOOK_DELETED` | Outbound webhook subscription lifecycle | | Webhooks | `OUTBOUND_WEBHOOK_VERIFICATION_KEY_REFRESHED` / `INBOUND_WEBHOOK_SETTINGS_UPDATED` | The delivery verification key rotates, or inbound webhook settings change | | Log access | `TOOL_CALL_LOGS_SEARCHED` / `TOOL_CALL_LOG_DETAIL_VIEWED` | A member searches the tool call logs, or opens one call | | Log access | `API_LOGS_SEARCHED` / `API_LOG_DETAIL_VIEWED` | A member searches the API request logs, or opens one request | | Log access | `WORKFORCE_LLM_LOGS_SEARCHED` / `WORKFORCE_LLM_LOG_DETAIL_VIEWED` / `WORKFORCE_LLM_LOG_PAYLOAD_VIEWED` | A member searches the LLM calls, opens one request, or opens its payload | | Log access | `WORKFORCE_SECURITY_ALERTS_SEARCHED` | A member searches the security alerts | | Log access | `AUDIT_LOG_EXPORTED` | A member exports the audit trail | | Chat sessions | `CHAT_SESSION_CREATED` / `CHAT_SESSION_ENDED` | An agent chat session starts or ends | | Organization | `WORKFORCE_ACTIVATED` | Workforce is activated for the organization | | Organization | `WORKFORCE_LOG_PAYLOADS_UPDATED` | Payload logging is turned on or off | | Organization | `ORGANIZATION_CLAIMED` / `ORGANIZATION_CLAIM_REISSUED` | The organization's first admin claim is redeemed or reissued | | Billing | `BILLING_PAYMENT_METHOD_ADDED` / `BILLING_PAYMENT_METHOD_UPDATED` | A payment method is added or changed | | Billing | `BILLING_PLAN_CHANGED` / `BILLING_SUBSCRIPTION_CANCELLED` / `ORG_SWITCHED_TO_EMPLOYEES_PRO` | The plan changes, the subscription is canceled, or the organization moves to the employees plan | | Billing | `BILLING_USER_SNAPSHOT_SUBMITTED` | A user-count snapshot is submitted for billing | Model provider credentials reuse the same `CREDENTIAL_*` names as employee Connector connections. The resource type on the row is what tells them apart. The skills events are described alongside the flows that write them in [Publishing skills](/merge-workforce/skills/publishing-skills), [Reviewing submissions](/merge-workforce/skills/reviewing-submissions), and [How agents load skills](/merge-workforce/skills/how-agents-load-skills). ## What an update entry looks like Update events pair an identifying prefix with a per-field diff, so you can scan the feed and see what changed without fetching the resource: ``` Updated Group Engineering with ID grp_4c81e2. Changed tool_packs: added Jira read-only; removed Salesforce ``` Every diffed value is truncated to 100 characters in the description. The event detail shows each changed field's old and new value side by side. ## Sensitive fields Secret values never reach an audit row in the first place: * **Auth-adjacent handlers omit the body.** Credential, SSO, sign-in, password reset, and API key handlers record that the action happened, with the entity named in the description, and store no request payload. * **Updates diff before mutating.** Fields holding secrets are summarized as `changed` rather than rendering the old and new value, so the description carries no secret material. Handlers that are not auth-adjacent do persist their validated request body as-is. If you handle especially sensitive configuration, review what those rows contain. ## Investigation flow **Who changed this?** Filter by event type, then read the resource column. Every event of that type comes back in order, with the user on each row. **What did this person do?** Filter by user. You see everything that member touched across resources, which is the check to run before revoking an admin's access. ## Exporting **Export** produces CSV of whatever filter is applied, so a compliance review that needs a 12-month window is a date filter and a download. The export itself is recorded as `AUDIT_LOG_EXPORTED`, so there is a trail of who pulled what. The CSV carries the event ID, timestamp in ISO 8601 UTC, event type, actor email and ID, role, IP address, resource type and ID, source, and the JSON-encoded diff for update events. Cells beginning with `=`, `+`, `-`, `@`, a tab, or a carriage return are prefixed with a single quote to neutralize CSV injection. For automated forwarding, the audit-trail export endpoint is documented in the [API reference](/merge-agent-handler/agent-handler/audit-log). ## Data retention One window covers audit events, [Tool call logs](/merge-workforce/logs/tool-calls), and the violation records behind [Violations and alerts](/merge-workforce/security/violations-and-alerts). The default is 90 days. Some plans keep data longer, and an Enterprise contract can set a window of its own, so read the window that applies to you off your plan on [Billing](/merge-workforce/settings/billing) or off your contract. Records belonging to an employee who has left follow the same window. Deprovisioning through [SCIM](/merge-workforce/provisioning/scim) revokes access immediately, and that employee's audit entries and tool call history are kept until the window closes, then purged. If your compliance requirements run longer than your window, export on a schedule and keep the results in your own systems. CSV export covers any filtered view, the audit-log endpoint covers audit events, and the log endpoints feed a warehouse or a [SIEM](/merge-workforce/logs/siem). ## What it doesn't capture The audit trail covers administrative actions in the dashboard and over the management API: changes to configuration and access, plus the few reads worth recording on their own. It does not include tool calls, model requests, or the OAuth steps that lead up to a `CREDENTIAL_CREATED` event. For the full picture, read it alongside [Tool call logs](/merge-workforce/logs/tool-calls) and [LLM calls](/merge-workforce/logs/gateway). ## Next Decide who on your team can perform audited actions, and who can read the trail, in [Team and roles](/merge-workforce/settings/team-and-roles).