Skip to main content
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.
ParameterInRequiredDescription
userIdbodyYesUser ID
toolIdbodyYesTool identifier (e.g. slack, linear)
instanceNamebodyYesDisplay name for this connection
secretbodyYesAPI key or token to encrypt and store
descriptionbodyNoOptional description
workspaceIdbodyNoWorkspace or project ID
parentIdbodyNoParent 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
ParameterInRequiredDescription
userIdbodyYesUser ID
namebodyYesEndpoint name (e.g. “Claude Desktop”)
descriptionbodyNoOptional 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.