Connections API - Toolshed

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

{
  "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):

{
  "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):

{
  "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.

​Tool connections

​Create a connection

​List connections

​Delete a connection

​Decrypt a secret (server-side only)

​MCP endpoints

​Create an endpoint

​List endpoints

​Delete an endpoint

​Encryption