# API Reference

The Keychains.dev REST API lets you programmatically manage connections, permissions, machines, and audit logs. All endpoints use JSON and require authentication via API key or session token.

## Base URL

`https://keychains.dev`

## Quick Start

1. Create an API key from the [dashboard](/content/dashboard/security/index.html) or via the CLI:

```
   keychains api-key create --name "My Script"
   ```

2. Use the key in the `Authorization` header:
   
   ```
   curl https://keychains.dev/api/machine/list \ 
     -H "Authorization: Bearer kc_your_api_key_here"
   ```

3. Or use the Node.js fetch API:
   
   ```
   const res = await fetch("https://keychains.dev/api/machine/list", {
     headers: { Authorization: "Bearer kc_your_api_key_here" }
   });
   const { machines } = await res.json();
   ```

## API Key Scope

### Allowed actions
- ✓ List and inspect machines
- ✓ Revoke machines
- ✓ List and inspect permissions
- ✓ Revoke permissions
- ✓ List and inspect connections
- ✓ Revoke connections
- ✓ Query and export audit logs
- ✓ Create and manage API keys

### Not allowed (requires full session)
- ✗ Access raw credentials (OAuth tokens, API key values)
- ✗ Approve new machines or permissions
- ✗ Create delegates
- ✗ Initiate new connections

## Endpoints

[**API Keys** \
Create and manage API keys for programmatic access.\
\
POST /api/api-keysGET /api/api-keysDELETE /api/api-keys/:keyId](/content/docs/api/api-keys/index.html)  
[**Connections** \
List, inspect, and manage OAuth and API key connections.\
\
GET /api/connectionsGET /api/connections/:idDELETE /api/connections/:id](/content/docs/api/connections/index.html)  
[**Permissions** \
List, inspect, and revoke permission requests.\
\
GET /api/permissionsGET /api/permissions/:idDELETE /api/permissions/:idPOST /api/permissions/:id/revalidate](/content/docs/api/permissions/index.html)  
[**Machines** \
List, inspect, and revoke linked machines.\
\
GET /api/machine/listGET /api/machine/:machineIdDELETE /api/machine/:machineId](/content/docs/api/machines/index.html)  
[**Audit Log** \
Query and export audit logs for compliance and monitoring.\
\
GET /api/audit-logGET /api/audit-log/export](/content/docs/api/audit-log/index.html)

## Pagination

List endpoints support pagination via query parameters:

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| page | integer | 1 | Page number |
| limit | integer | 50 | Items per page (max 100) |

## Errors

All error responses follow a consistent JSON format:

```json
{
  "error": "unauthorized",
  "error_description": "Authentication required"
}
```

| Code | Meaning |
| --- | --- |
| 200 | Success |
| 201 | Created |
| 202 | Accepted (async operation started) |
| 400 | Bad request — invalid parameters |
| 401 | Unauthorized — missing or invalid authentication |
| 403 | Forbidden — insufficient permissions |
| 404 | Not found |
| 500 | Server error |