Audit API

Endpoints

Method	Path	Scope	Description
GET	/v1/audit/logs	audit:read	List security audit events

Access Control

• Admins see all events and can filter by merchant_id
• Merchants are automatically scoped to their own events

Query Parameters

Param	Type	Description
merchant_id	UUID	Filter by merchant (admin only)
event_type	string	e.g. auth.failed, auth.rate_limited
severity	string	info, warn, or critical
since	datetime	Start of date range (ISO 8601)
until	datetime	End of date range (ISO 8601)
page	int	Page number
page_size	int	Items per page (max 100)

Response

{
  "success": true,
  "data": [
    {
      "id": "log-uuid-...",
      "event_type": "auth.failed",
      "severity": "warn",
      "actor_ip": "192.168.1.1",
      "merchant_id": null,
      "key_prefix": "sk_test_abc",
      "detail": null,
      "metadata": null,
      "created_at": "2025-01-01T12:00:00Z"
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 1 }
}

Event Types

Event	Severity	Trigger
auth.success	info	Successful authentication
auth.failed	warn	Invalid or unknown API key
auth.key_expired	warn	Expired key used
auth.merchant_inactive	warn	Key belongs to deactivated merchant
auth.invalid_format	warn	Malformed key rejected before DB hit
auth.rate_limited	critical	IP blocked after 10 failures
auth.scope_denied	warn	Key missing required scope
key.created	info	New API key generated
key.revoked	critical	API key deactivated