# 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', '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

```json
{
  "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**

```bash
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**

```javascript
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

```json
{
  "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**

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

**Node.js**

```javascript
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

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

### Examples

**curl**

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

**Node.js**

```javascript
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](/content/docs/api/api-keys/index.html) [Permissions](/content/docs/api/permissions/index.html)