Audit Logging
The audit trail for all external actions agents take, including API proxy requests, MCP tool calls, policy decisions, and administrative changes.
Superagent maintains three audit logs that together give you full visibility into what your agents are doing and what changes administrators have made. API proxy requests and MCP tool calls are logged per-agent. Administrative changes (creating agents, updating policies, managing users) are logged globally.
API proxy audit log
Every HTTP request an agent makes through the API proxy is recorded in the proxy_audit_log table. This covers all calls to connected account APIs --- Gmail, GitHub, Slack, Salesforce, and every other provider.
Each entry captures:
| Field | Description |
|---|---|
| Agent | The agent slug that made the request |
| Account | The connected account ID used |
| Toolkit | The provider (e.g., gmail, github, slack) |
| Target host | The API hostname (e.g., api.github.com) |
| Target path | The request path (e.g., repos/owner/repo/issues) |
| Method | The HTTP method (GET, POST, PUT, DELETE, etc.) |
| Status code | The upstream API's response status code |
| Policy decision | How the request was authorized (see below) |
| Matched scopes | JSON array of OAuth scopes the request matched against |
| Error message | Set if the request failed at the proxy level (token validation failure, host not allowed, etc.) |
| Timestamp | When the request was made |
Audit entries are written for every request, including ones that are blocked or fail validation. This means you can see unauthorized access attempts, not just successful calls.
MCP audit log
Requests proxied to remote MCP servers are recorded in the mcp_audit_log table. This covers all tool calls and protocol messages an agent sends through registered MCP servers.
Each entry captures:
| Field | Description |
|---|---|
| Agent | The agent slug that made the request |
| MCP server | The remote MCP server ID and name |
| Method | The HTTP method |
| Request path | The JSON-RPC method or HTTP path. For tool calls, this is formatted as tools/call: tool_name |
| Status code | The MCP server's response status code |
| Duration | Request duration in milliseconds |
| Policy decision | How the request was authorized |
| Matched tool | The specific tool name for tools/call requests |
| Error message | Set if the request failed |
| Timestamp | When the request was made |
Protocol-level MCP methods (handshake, tool discovery, pings) are always allowed without policy checks, but tool invocations go through the same policy enforcement as API proxy requests.
Policy decisions
Both audit logs record the policy decision that governed each request. The possible values are:
| Decision | Meaning |
|---|---|
allow | Automatically allowed by a scope policy, account default, or global default |
approved_by_user | The request required review, and the user approved it |
block | Automatically blocked by a scope policy |
denied_by_user | The request required review, and the user denied it |
review_timeout | The request required review, but the user did not respond in time |
Policy resolution follows a hierarchy. For API proxy requests:
- Scope policy --- If the request matches a specific scope with an explicit policy, that policy applies.
- Account default --- If no scope-specific policy exists, the account's default policy (the
*scope) applies. - Global default --- If neither exists, the global default API policy from user settings applies.
When multiple scopes match a request, the most permissive decision wins. For MCP requests, the hierarchy is: explicit tool policy, then MCP default (*), then global default.
Browsing the per-agent audit log
Each agent has an API Logs view accessible from the agent's home page. This view merges entries from both the proxy and MCP audit logs into a single chronological timeline.
The log table displays:
- Timestamp --- When the request was made, formatted as
MM/dd/yy, HH:mm:ss - Duration --- How long the request took (MCP requests only)
- Source --- Either "API" (proxy) or "MCP", shown as a colored badge
- Method --- The HTTP method, color-coded by verb
- Status --- The response status code, color-coded (green for 2xx, red for 4xx+)
- Policy --- The policy decision badge (auto-allowed, user-approved, auto-blocked, user-denied, or timeout)
- Toolkit --- The provider name or MCP server name
- Path --- The target URL or request path, with error messages shown inline in red
Click any row to expand a detail panel showing the full path, source type, matched scopes, duration, error details, and precise timestamp.
The view is paginated (15 entries per page) with a refresh button to load the latest entries.
Administrative audit log
The global Audit Log tab in Settings tracks administrative actions across the deployment. This is separate from the per-agent API/MCP logs and records changes to the system's configuration.
Tracked objects and actions
| Object | Actions |
|---|---|
| agent | created, updated, deleted, imported, exported |
| agent_access | granted, revoked, changed |
| account | connected, disconnected, assigned, unassigned |
| mcp | created, updated, deleted, assigned, unassigned |
| trigger | created, updated, deleted, paused, resumed |
| task | created, updated, deleted, paused, resumed |
| chat_integration | created, updated, deleted |
| skill | created, updated, exported |
| secret | created, updated, deleted |
| file | uploaded |
| mount | created, deleted |
| settings | updated, factory_reset |
| policy | updated |
| user | invited, reset_password |
Each entry records the timestamp, the user who performed the action (in auth mode), the object type, the action, the object ID (e.g., the agent slug or account ID), and an optional details field with additional context as a JSON object.
Filtering
The audit log UI provides three filter dropdowns:
- Object --- Filter by object type (agent, account, mcp, trigger, etc.)
- Action --- Filter by action. The available actions update based on the selected object type.
- User --- Filter by the user who performed the action. Only available in auth mode.
The log is paginated (25 entries per page) and sorted by timestamp, newest first.
Auth mode
The administrative audit log is restricted to admin users. The API endpoint (/api/audit-log) requires both authentication and admin role. In auth mode, each audit entry includes the user ID of the person who performed the action, and the User filter column appears in the table with user names and email tooltips.