Documentation
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.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

Pagination

List endpoints support pagination via query parameters:

ParameterTypeDefaultDescription
pageinteger1Page number
limitinteger50Items per page (max 100)

Errors

All error responses follow a consistent JSON format:

{
  "error": "unauthorized",
  "error_description": "Authentication required"
}
CodeMeaning
200Success
201Created
202Accepted (async operation started)
400Bad request — invalid parameters
401Unauthorized — missing or invalid authentication
403Forbidden — insufficient permissions
404Not found
500Server error