Audit Log

Query and export audit logs for compliance, monitoring, and debugging. Every proxy request, machine event, and permission change is logged.

GET /api/audit-log

Query audit logs for the authenticated user. Supports filtering by machine, permission, provider, method, event type, and date range. Results are paginated.

Authentication

API key, Session cookie, or Machine JWT

Query Parameters

Name Type Description
machineId string Filter by machine ID
permissionRequestId string Filter by permission request ID
provider string Filter by provider (e.g., 'github.com')
method string Filter by HTTP method (e.g., 'GET', 'POST')
eventType string Filter by event type (see below)
startDate string ISO date string — start of date range
endDate string ISO date string — end of date range
page integer Page number (default: 1)
limit integer Items per page (default: 50, max: 100)
action string Set to 'filters' to get available filter values

Response

{
  "entries": [
    {
      "id": "evt_abc123",
      "timestamp": "2026-02-17T14:30:00.000Z",
      "eventType": "proxy_call",
      "machineId": "m_8f3a...",
      "permissionRequestId": "pr_a1b2c3",
      "provider": "github.com",
      "method": "GET",
      "endpoint": "/user/repos",
      "statusCode": 200
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 50
}

Examples

curl

curl "https://keychains.dev/api/audit-log?limit=10" \
  -H "Authorization: Bearer kc_your_api_key"

# Filter by provider and date range
curl "https://keychains.dev/api/audit-log?provider=github.com&startDate=2026-02-01" \
  -H "Authorization: Bearer kc_your_api_key"

# Get available filter options
curl "https://keychains.dev/api/audit-log?action=filters" \
  -H "Authorization: Bearer kc_your_api_key"

Node.js

const res = await fetch(
  "https://keychains.dev/api/audit-log?limit=10&provider=github.com",
  { headers: { Authorization: "Bearer kc_your_api_key" } }
);
const { entries, total, page } = await res.json();

Event Types

Event Type Description
proxy_call An API request was proxied through Keychains
machine_linked A machine was linked to a user account
machine_revoked A machine was revoked
permission_created A new permission request was created
permission_revoked A permission was revoked
permission_revalidation A permission was set to needs_revalidation
scopes_approved Scopes were approved on a permission

GET /api/audit-log/export

Export audit logs as a JSONL (newline-delimited JSON) stream. Useful for compliance exports and bulk analysis. Returns a streaming response.

Authentication

API key, Session cookie, or Machine JWT

Query Parameters

Name Type Description
startDate string ISO date string — start of date range
endDate string ISO date string — end of date range
eventType string Filter by event type
machineId string Filter by machine ID
provider string Filter by provider

Response

Content-Type: application/x-ndjson
Content-Disposition: attachment; filename="audit-export-2026-02-17.jsonl"

{"id":"evt_1","timestamp":"2026-02-17T14:30:00Z","eventType":"proxy_call",...}
{"id":"evt_2","timestamp":"2026-02-17T14:31:00Z","eventType":"proxy_call",...}

Examples

curl

# Download audit log export
curl "https://keychains.dev/api/audit-log/export?startDate=2026-02-01" \
  -H "Authorization: Bearer kc_your_api_key" \
  -o audit-export.jsonl

Node.js

const res = await fetch(
  "https://keychains.dev/api/audit-log/export?startDate=2026-02-01",
  { headers: { Authorization: "Bearer kc_your_api_key" } }
);

// Stream the response
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split("\n");
  buffer = lines.pop() || "";
  for (const line of lines) {
    if (line.trim()) {
      const entry = JSON.parse(line);
      console.log(entry);
    }
  }
}

Machines