API Reference
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.devQuick Start
1. Create an API key from the dashboard 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
Connections
List, inspect, and manage OAuth and API key connections.
GET /api/connectionsGET /api/connections/:idDELETE /api/connections/:id
Permissions
List, inspect, and revoke permission requests.
GET /api/permissionsGET /api/permissions/:idDELETE /api/permissions/:idPOST /api/permissions/:id/revalidate
Machines
List, inspect, and revoke linked machines.
GET /api/machine/listGET /api/machine/:machineIdDELETE /api/machine/:machineId
Audit Log
Query and export audit logs for compliance and monitoring.
GET /api/audit-logGET /api/audit-log/export
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:
{
"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 |