> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toolshed.philo.ventures/llms.txt
> Use this file to discover all available pages before exploring further.

# Connections API

> CRUD API for tool connections and MCP endpoints with encrypted secret storage.

The connections API manages API keys and secrets for connected tools. All secrets are encrypted at rest using AES-256-GCM before being stored in the database.

## Tool connections

### Create a connection

```
POST /api/connections
```

Encrypts the secret and stores the connection. Returns a masked version of the secret — the raw value is never returned after creation.

| Parameter      | In   | Required | Description                                                                                                      |
| -------------- | ---- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `userId`       | body | Yes      | User ID                                                                                                          |
| `toolId`       | body | Yes      | Tool identifier (e.g. `slack`, `linear`)                                                                         |
| `instanceName` | body | Yes      | Display name for this connection                                                                                 |
| `secret`       | body | Yes      | API key or token to encrypt and store                                                                            |
| `description`  | body | No       | Optional description                                                                                             |
| `workspaceId`  | body | No       | Workspace or project ID                                                                                          |
| `parentId`     | body | No       | Parent connection ID (for nested instances under a multi-instance tool, e.g. project rows under a workspace row) |

**Response (201):**

```json theme={null}
{
  "id": "uuid",
  "toolId": "slack",
  "instanceName": "Philo Workspace",
  "maskedSecret": "••••••••ab3f"
}
```

***

### List connections

```
GET /api/connections?userId=<userId>
```

Returns all connections for a user. Secrets are always masked.

**Response (200):**

```json theme={null}
{
  "connections": [
    {
      "id": "uuid",
      "user_id": "user-123",
      "tool_id": "slack",
      "instance_name": "Philo Workspace",
      "masked_secret": "••••••••ab3f",
      "workspace_id": null,
      "parent_id": null,
      "created_at": "2026-04-24T00:00:00Z",
      "updated_at": "2026-04-24T00:00:00Z"
    }
  ]
}
```

***

### Delete a connection

```
DELETE /api/connections/:id?userId=<userId>
```

Deletes the connection and any child connections (e.g. projects under an account).

***

### Decrypt a secret (server-side only)

```
POST /api/connections/:id/decrypt
```

Decrypts and returns the raw secret. Used internally by token vending when a tool needs the actual API key. This endpoint should not be exposed to clients.

***

## MCP endpoints

MCP endpoints are user-specific URLs with unique tokens for connecting AI tools to Toolshed.

### Create an endpoint

```
POST /api/connections/mcp-endpoints
```

| Parameter     | In   | Required | Description                           |
| ------------- | ---- | -------- | ------------------------------------- |
| `userId`      | body | Yes      | User ID                               |
| `name`        | body | Yes      | Endpoint name (e.g. "Claude Desktop") |
| `description` | body | No       | Optional description                  |

**Response (201):**

```json theme={null}
{
  "id": "uuid",
  "name": "Claude Desktop",
  "token": "ts_mcp_a1b2c3d4e5f6...",
  "createdAt": "2026-04-24T00:00:00Z"
}
```

### List endpoints

```
GET /api/connections/mcp-endpoints?userId=<userId>
```

### Delete an endpoint

```
DELETE /api/connections/mcp-endpoints/:id?userId=<userId>
```

## Encryption

Secrets are encrypted using AES-256-GCM with a key derived from `BETTER_AUTH_SECRET` via SHA-256. The encrypted format is `base64(iv):base64(ciphertext)`. The encryption key never leaves the server.