Audit API

The Audit API provides access to comprehensive audit logs for all permission requests, approvals, and token usage.

Endpoints

  • GET /v1/audit - Query audit logs
  • GET /v1/audit/:id - Get a specific audit entry
  • POST /v1/audit/export - Export audit logs

Query Audit Logs

Search and filter audit logs.

Request

GET /v1/audit?agent_id=agent_xxxx&event_type=request&limit=50
Authorization: Bearer your_user_token

Query Parameters

ParameterTypeDescription
agent_idstringFilter by agent ID
permission_idstringFilter by permission request ID
event_typestringEvent type filter (see below)
actionstringFilter by action (e.g., "email.send")
start_datestringISO 8601 start date
end_datestringISO 8601 end date
limitnumberResults per page (default: 50, max: 1000)
cursorstringPagination cursor

Event Types

TypeDescription
requestPermission was requested
approvePermission was approved
denyPermission was denied
useToken was used
expireToken expired unused
revokeToken was revoked

Response

{
  "data": [
    {
      "id": "audit_xxxxxxxxxxxx",
      "user_id": "user_xxxx",
      "agent_id": "agent_xxxx",
      "permission_request_id": "perm_xxxx",
      "event_type": "approve",
      "details": {
        "action": "email.send",
        "resource": "email:client@example.com",
        "scope": {
          "max_emails": 1
        },
        "decided_by": "user",
        "decision_reason": "Manual approval",
        "policy_id": null
      },
      "ip_address": "192.168.1.1",
      "user_agent": "AgentOTP-SDK/1.0.0",
      "created_at": "2026-01-28T12:00:30Z"
    }
  ],
  "has_more": true,
  "next_cursor": "cursor_xxxx"
}

Get Audit Entry

Get details of a specific audit log entry.

GET /v1/audit/:id
Authorization: Bearer your_user_token

Export Audit Logs

Export audit logs in various formats for compliance reporting.

Request

POST /v1/audit/export
Content-Type: application/json
Authorization: Bearer your_user_token
{
  "format": "csv",
  "start_date": "2026-01-01T00:00:00Z",
  "end_date": "2026-01-31T23:59:59Z",
  "agent_id": "agent_xxxx",
  "event_types": ["request", "approve", "deny"],
  "include_details": true
}

Export Parameters

FieldTypeDescription
formatstringExport format: csv, json, or parquet
start_datestringISO 8601 start date (required)
end_datestringISO 8601 end date (required)
agent_idstringFilter by agent ID
event_typesstring[]Filter by event types
include_detailsbooleanInclude full details JSON

Response

{
  "export_id": "export_xxxxxxxxxxxx",
  "status": "processing",
  "download_url": null,
  "expires_at": null,
  "created_at": "2026-01-28T12:00:00Z"
}

Poll the export status or use webhooks to get notified when the export is ready:

GET /v1/audit/export/:export_id
Authorization: Bearer your_user_token
{
  "export_id": "export_xxxxxxxxxxxx",
  "status": "completed",
  "download_url": "https://exports.agentotp.com/export_xxxx.csv",
  "expires_at": "2026-01-29T12:00:00Z",
  "row_count": 15420,
  "file_size_bytes": 2048576,
  "created_at": "2026-01-28T12:00:00Z",
  "completed_at": "2026-01-28T12:01:30Z"
}

Audit Log Retention

Audit logs are retained based on your plan:

PlanRetention
Free7 days
Pro90 days
Team1 year
EnterpriseCustom (up to 7 years)

Webhooks

Configure webhooks to receive real-time audit events:

// Webhook payload
{
  "event": "audit.created",
  "timestamp": "2026-01-28T12:00:30Z",
  "data": {
    "id": "audit_xxxxxxxxxxxx",
    "event_type": "approve",
    "agent_id": "agent_xxxx",
    "permission_request_id": "perm_xxxx",
    "details": { ... }
  }
}

Compliance Reports

Enterprise customers can generate compliance reports:

POST /v1/audit/reports/compliance
Content-Type: application/json
Authorization: Bearer your_user_token
{
  "report_type": "soc2",
  "period": {
    "start": "2026-01-01",
    "end": "2026-03-31"
  },
  "format": "pdf"
}

See Also