> This page is for Agent Handler. > 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's in the Agent Handler Audit Trail: event catalog, retention, CSV export, and how to use it for compliance. The Audit Trail records every admin action taken in your Agent Handler organization: member invitations, role changes, Access Key rotations, OAuth credential edits, security rule changes, Tool Pack edits, and the handful of reads worth recording on their own, such as a log search. It's the artifact your security review will ask for, and the evidence you'll pull when you need to know who changed what and when. Different from the [Tool Call Logs](/merge-agent-handler/observe/tool-call-logs) (which capture agent activity) and the [API Request Logs](/merge-agent-handler/observe/api-request-logs) (which capture your backend's calls). The Audit Trail is specifically about administrative actions on the dashboard or via the management API. ## What's captured For each event: * **Event type.** What was done, such as `ROLE_UPDATED`, `PRODUCTION_API_KEY_REVOKED`, or `TOOL_PACK_CREATED`. * **Actor.** The dashboard user (or the API key) that performed the action. * **Resource.** What was changed - Registered User ID, Tool Pack ID, rule ID, member ID. * **Before/after diff.** For updates, the specific fields that changed and their old and new values. * **Source.** Web dashboard, API, or system (for automated actions like SCIM-driven changes). * **IP address** of the actor, when available. * **Timestamp.** ## 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. | 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 | | 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 IdP connection is configured, edited, or removed | | Single sign-on | `SSO_LOGIN_REQUIRED` / `SSO_LOGIN_NOT_REQUIRED` / `SSO_LOGIN_REQUIRED_ON` / `SSO_LOGIN_REQUIRED_OFF` | Whether members have to sign in through the IdP 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` | The IdP 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 IdP | | SCIM provisioning | `SCIM_GROUP_ACCESS_UPDATED` | A Group's tool access changes | | SCIM provisioning | `SCIM_DEFAULT_ACCESS_UPDATED` | The default access for a user whose Group has no mapping changes | | Tool access requests | `SCIM_TOOL_ACCESS_REQUEST_CREATED` | An employee requests a tool they don't have | | Tool access requests | `SCIM_TOOL_ACCESS_REQUEST_APPROVED` / `SCIM_TOOL_ACCESS_REQUEST_DENIED` | A reviewer approves or denies a request | | Tool access requests | `SCIM_TOOL_ACCESS_REQUEST_REVOKED` / `SCIM_TOOL_ACCESS_REQUEST_CANCELED` | An approved grant is withdrawn, or the requester cancels | | Access keys and tokens | `PRODUCTION_API_KEY_CREATED` / `PRODUCTION_API_KEY_REVOKED` | A production Access Key is created or revoked | | Access keys and tokens | `PRODUCTION_API_KEY_REGENERATED` | A production key is regenerated in place, which is how the master key rotates | | Access keys and tokens | `TEST_API_KEY_CREATED` / `TEST_API_KEY_REGENERATED` / `TEST_API_KEY_REVOKED` / `TEST_API_KEY_DELETED` | Test key lifecycle | | Access 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-agent-handler/build/connecting-agents/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 | | OAuth apps | `APPLICATION_CREDENTIAL_CREATED` / `APPLICATION_CREDENTIAL_UPDATED` / `APPLICATION_CREDENTIAL_DELETED` | Your own OAuth app for a Connector is added, edited, or removed | | Connections and credentials | `CREDENTIAL_CREATED` / `CREDENTIAL_UPDATED` / `CREDENTIAL_DELETED` | A Registered User's connection to a Connector is stored, changed, or revoked | | Connections and credentials | `CREDENTIAL_EXPORTED` / `CREDENTIAL_EXPORT_FAILED` | A credential export succeeds or fails | | Connections and credentials | `CREDENTIAL_EXPORT_KEY_REGISTERED` / `CREDENTIAL_EXPORT_KEY_REVOKED` | A public key for credential export is registered or revoked | | Tool Packs | `TOOL_PACK_CREATED` / `TOOL_PACK_UPDATED` / `TOOL_PACK_DELETED` | Tool Pack lifecycle and configuration changes | | Registered Users | `REGISTERED_USER_CREATED` / `REGISTERED_USER_DELETED` | A Registered User is created or deleted | | Security rules | `SECURITY_RULE_CREATED` / `SECURITY_RULE_UPDATED` / `SECURITY_RULE_DELETED` | A [Security Gateway](/merge-agent-handler/secure/security-gateway) rule or per-Tool-Pack override is created, edited, or deleted | | 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` | A Merge-provided skill is turned on or off for the org | | Skills | `SKILL_DELETED` | A skill is deleted | | Skills | `SKILL_RETRIEVED` | An agent loads a skill with `retrieve_skill` | | Webhooks | `OUTBOUND_WEBHOOK_CREATED` / `OUTBOUND_WEBHOOK_UPDATED` / `OUTBOUND_WEBHOOK_DELETED` | Outbound webhook subscription lifecycle | | Webhooks | `OUTBOUND_WEBHOOK_VERIFICATION_KEY_REFRESHED` | The key used to verify deliveries is rotated | | Webhooks | `INBOUND_WEBHOOK_SETTINGS_UPDATED` | 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 | `AUDIT_LOG_EXPORTED` | A member exports the Audit Trail | | 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 | | Chat sessions | `CHAT_SESSION_CREATED` / `CHAT_SESSION_ENDED` | An agent chat session starts or ends | | Copilot | `COPILOT_INTEGRATION_BOUND` / `COPILOT_INTEGRATION_REBOUND` / `COPILOT_INTEGRATION_UNBOUND` | A Copilot Studio integration is bound to a Tool Pack, rebound, or unbound | | Organization settings | `ALLOWED_CALLBACK_ORIGIN_CREATED` / `ALLOWED_CALLBACK_ORIGIN_DELETED` | A callback origin is added or removed | | Organization settings | `LINK_CONFIGURATION_UPDATED` | [Link customization](/merge-agent-handler/build/authentication/link-customization) changes | | Organization settings | `GIT_SETTINGS_CREATED` / `GIT_SETTINGS_UPDATED` / `GIT_SETTINGS_DELETED` | The organization's Git settings change | | Organization settings | `DEFAULT_RESOURCES_CREATED` | Default resources are created for a new organization | | Agent signup | `AGENT_SIGNUP` | An agent creates its own organization, as covered in [Agent quickstart](/merge-agent-handler/setup/agent-quickstart) | | Agent signup | `ORGANIZATION_CLAIMED` | A person claims an agent-created organization and becomes its first Admin | | Agent signup | `ORGANIZATION_CLAIM_REISSUED` | A claim link is revoked and replaced with a fresh one | | Billing | `BILLING_PAYMENT_METHOD_ADDED` / `BILLING_PAYMENT_METHOD_UPDATED` | A payment method is added or updated | | Billing | `BILLING_PLAN_CHANGED` / `ORG_SWITCHED_TO_EMPLOYEES_PRO` | The organization's plan changes | | Billing | `BILLING_SUBSCRIPTION_CANCELLED` | The subscription is canceled | | Billing | `BILLING_USER_SNAPSHOT_SUBMITTED` | A user-count snapshot is submitted for billing | The Skills events are described alongside the flows that write them in [Publishing skills](/merge-agent-handler/build/skills/publishing-skills), [Reviewing submissions](/merge-agent-handler/build/skills/reviewing-submissions), and [How agents load skills](/merge-agent-handler/build/skills/how-agents-load-skills). ## Where to view it [Settings → Audit Trail](https://ah.merge.dev/settings/audit-trail). The default view is the last 7 days, all events. The filter bar supports event type, actor, resource type, date range, and source. Click any row to open the event detail with the full diff. For events that touched multiple fields, every field's old and new value is shown side by side. ## Investigation flow **"Who changed this?"** Filter by resource type and ID. The Audit Trail shows every event against that resource in chronological order with the actor on each row. **"What did this person do?"** Filter by actor. You'll see everything that member touched across resources - useful when offboarding, before revoking access. ## Exporting The **Export** button produces CSV of whatever filter is currently applied. For compliance reviews where you need to show a 12-month window, set the date filter and export. The CSV includes: * Event ID * Timestamp (ISO 8601, UTC) * Event type * Actor email and ID * Resource type and ID * Source (dashboard, API, system) * Diff (JSON-encoded before/after for update events) For automated forwarding to a SIEM or data warehouse, 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-agent-handler/observe/tool-call-logs), and the violation records behind [Violations and alerts](/merge-agent-handler/secure/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 and usage](/merge-agent-handler/administer/billing) or off your contract. Records belonging to a user who is gone follow the same window. Deprovisioning through [SCIM](/merge-agent-handler/administer/scim-provisioning) or deleting a [Registered User](/merge-agent-handler/build/users/registered-users) revokes access immediately, and their audit entries and tool-call history are kept until the window closes, then purged. If your compliance requirements need longer than your window, export on a schedule and keep the results in your own systems. CSV export covers any filtered view in the dashboard, the audit-log endpoint covers audit events, and the log endpoints feed a warehouse or a [SIEM](/merge-agent-handler/observe/stream-logs-to-a-siem). ## What it doesn't capture The Audit Trail covers administrative actions in the dashboard and over the management API. That is mostly changes to configuration and access, plus the few reads worth recording on their own: a log search, a log detail view, an agent loading a skill, and a sign-in. It doesn't include tool calls (see [Tool Call Logs](/merge-agent-handler/observe/tool-call-logs)), backend API requests (see [API Request Logs](/merge-agent-handler/observe/api-request-logs)), or the OAuth-flow steps that lead up to a `CREDENTIAL_CREATED` event. For the full picture, combine the three streams. ## Next Manage who on your team can do what with [Team and roles](/merge-agent-handler/administer/team-and-roles).