Connector Audit Logging

Every call to an external connector tool — whether via MCP, Telegram, or ChatGPT — is logged in the Connector Audit Log for compliance, cost tracking, and security investigation.

What is logged

Audit log query API

List audit entries

GET /api/audit/connectors

Query parameters:

Example:

curl https://aacworkflow.example.com/api/audit/connectors \
  ?platform=mcp \
  &outcome=error \
  &since=2025-06-01T00:00:00Z \
  &limit=50

Returns:

{
  "entries": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440001",
      "user_id": "550e8400-e29b-41d4-a716-446655440002",
      "platform": "mcp",
      "tool_name": "update_issue",
      "scopes": ["issues:write", "issues:read"],
      "outcome": "ok",
      "error_code": null,
      "input_summary": "issue_id: AAC-42, status: done",
      "result_size": 2048,
      "tokens_in": 150,
      "tokens_out": 80,
      "cost_micros": 12,
      "created_at": "2025-06-22T15:30:00Z",
      "duration_ms": 245
    }
  ],
  "total": 1247,
  "limit": 50,
  "offset": 0
}

Audit log UI

Workspace admins can view the audit log in Settings → Audit & Compliance → Connector Log.

The UI provides:

• Timeline view — recent tool calls with status indicators (green = success, yellow = denied, red = error)
• Filtering — by platform, tool, outcome, user, and date range
• Cost analysis — sum of token costs over a period
• Incident investigation — drill down into failed or denied calls to understand why

Example: Investigate a suspicious error spike

1. Go to Settings → Audit & Compliance → Connector Log
2. Filter by platform: mcp, outcome: error, since: yesterday
3. Click on a failed call to see:
   • Which tool was called
   • What error occurred
   • Who initiated the call
   • Full token scopes at the time
4. Correlate with agent execution logs to understand context

Redaction policy

The audit log never stores:

• API tokens or secrets
• Full request/response bodies
• PII beyond what the result itself exposes

The input_summary field redacts sensitive data:

• ❌ input_summary: "token=sk-..." — redacted
• ✓ input_summary: "issue_id: AAC-42, status: done" — safe
• ✓ input_summary: "create issue, title length: 45 chars, 3 labels" — safe

Scope enforcement + audit

When a tool is called with insufficient scopes:

1. Call is denied — the tool never executes
2. Audit logs the denial — outcome is denied, error_code is insufficient_scope
3. No mutation happens — the call is logged but takes no action

Example denial log:

{
  "platform": "mcp",
  "tool_name": "delete_issue",
  "scopes": ["issues:read"],
  "outcome": "denied",
  "error_code": "insufficient_scope",
  "input_summary": "issue_id: AAC-100",
  "created_at": "2025-06-22T16:00:00Z"
}

Cost & usage tracking

For calls that drive a language model (e.g., agents invoking tools via MCP), the audit log captures:

• tokens_in — input tokens sent to the model
• tokens_out — output tokens received
• cost_micros — estimated cost (pricing varies by model)

Admins can query the audit log to:

• Forecast costs — sum cost_micros over the billing period
• Detect runaway agents — find users/workspaces with unusual token counts
• Optimize prompts — identify which tools have the highest input token overhead

Example cost query:

curl https://aacworkflow.example.com/api/audit/connectors \
  ?since=2025-06-01&until=2025-06-30 \
  | jq '[.entries[] | .cost_micros] | add'
# Returns total cost in microdollars for June

Compliance and retention

• Audit logs are retained for 90 days by default (configurable per workspace)
• Logs are immutable — they cannot be edited or deleted
• Logs are indexed by workspace — one workspace cannot view another's audit trail
• Deletion of workspace, user, or token does not retroactively delete audit entries (historical record)

Security notes

• Audit writes are fire-and-forget — failures to log do not block tool execution
• Audit data is encrypted at rest (same encryption as issue data)
• Audit queries require workspace admin role
• Audit entries carry the workspace_id, preventing cross-workspace data leakage

Example workflows

1. Investigate a support ticket

"User says an issue update failed. Let me check the audit log."

curl https://aacworkflow.example.com/api/audit/connectors \
  ?user_id=<user_id> \
  &tool=update_issue \
  &outcome=error \
  &since=2025-06-22T00:00:00Z

You see that the call failed with insufficient_scope. The user's token only had issues:read, not issues:write.

2. Monitor Telegram bot usage

"How many tools did our Telegram bot call this week?"

curl https://aacworkflow.example.com/api/audit/connectors \
  ?platform=telegram \
  &since=2025-06-15T00:00:00Z \
  | jq '.total'

Result: 342 tool calls via Telegram this week.

3. Calculate costs

"What did our MCP tools cost in June?"

curl https://aacworkflow.example.com/api/audit/connectors \
  ?platform=mcp \
  &since=2025-06-01 \
  &until=2025-06-30 \
  | jq '[.entries[] | select(.cost_micros != null) | .cost_micros] | add'

Result: 45,000 microdollars = $0.045

4. Find denied calls

"Why are some tool calls being denied? Let me check."

curl https://aacworkflow.example.com/api/audit/connectors \
  ?outcome=denied \
  &since=yesterday

Result: 12 calls denied due to insufficient_scope, 1 due to malformed_input.