API Reference

Connections

Manage OAuth and API key connections to third-party services. Connections represent linked accounts (e.g., GitHub OAuth, Stripe API key).

GET/api/connections

List all connections for the authenticated user. Supports filtering by provider, status, and scopes.

Authentication

API key, Session cookie, or Machine JWT

Query Parameters

Name	Type	Description
provider	string	Filter by provider slug (e.g., 'github', 'stripe')
providers	string	Comma-separated list of providers to filter
status	string	Filter by status: 'active' (default), 'pending', 'expired', 'error', or 'all'
scopes	string	Space-separated scopes to filter (e.g., 'github::repo')
q	string	Search query to filter by provider name
refresh	boolean	Set to 'true' to invalidate cache and fetch fresh data

Response

{
  "connections": [
    {
      "id": "conn_abc123",
      "provider": "github",
      "displayName": "GitHub",
      "domain": "github.com",
      "type": "oauth",
      "status": "active",
      "accountIdentifier": "octocat",
      "scopes": ["repo", "user"],
      "createdAt": "2026-02-10T08:00:00.000Z"
    }
  ],
  "total": 1
}

Examples

curl

curl https://keychains.dev/api/connections \
  -H "Authorization: Bearer kc_your_api_key"

# Filter by provider
curl "https://keychains.dev/api/connections?provider=github" \
  -H "Authorization: Bearer kc_your_api_key"

Node.js

const res = await fetch("https://keychains.dev/api/connections", {
  headers: { Authorization: "Bearer kc_your_api_key" },
});
const { connections } = await res.json();

GET/api/connections/:connectionId

Get details of a specific connection by its ID.

Authentication

API key, Session cookie, or Machine JWT

Response

{
  "id": "conn_abc123",
  "provider": "github",
  "displayName": "GitHub",
  "domain": "github.com",
  "type": "oauth",
  "status": "active",
  "accountIdentifier": "octocat",
  "scopes": ["repo", "user"],
  "createdAt": "2026-02-10T08:00:00.000Z"
}

Examples

curl

curl https://keychains.dev/api/connections/conn_abc123 \
  -H "Authorization: Bearer kc_your_api_key"

Node.js

const res = await fetch("https://keychains.dev/api/connections/conn_abc123", {
  headers: { Authorization: "Bearer kc_your_api_key" },
});
const connection = await res.json();

DELETE/api/connections/:connectionId

Revoke and delete a connection. This removes the linked account and invalidates cached credentials. The operation is asynchronous — the response returns immediately with status 202.

Authentication

API key, Session cookie, or Machine JWT

Response

{
  "success": true,
  "id": "conn_abc123",
  "pending": true,
  "cacheRemoved": true
}

Examples

curl

curl -X DELETE https://keychains.dev/api/connections/conn_abc123 \
  -H "Authorization: Bearer kc_your_api_key"

Node.js

const res = await fetch("https://keychains.dev/api/connections/conn_abc123", {
  method: "DELETE",
  headers: { Authorization: "Bearer kc_your_api_key" },
});
const { success } = await res.json();

API Keys Permissions