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 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:

Errors

All error responses follow a consistent JSON format:

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