# 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](/content/docs/api/machines/index.html)