Connections

A connection holds the credentials for one account on one provider (e.g. an acme-workspace account on slack). Actions, the proxy, and MCP tools all run against a connection. Credentials are encrypted at rest with AES-256-GCM and OAuth tokens are refreshed for you.

A connection is identified by two values:

• provider_config_key — which provider/config (e.g. slack, github).
• connection_id — which account under that provider (e.g. acme-workspace). If you don't supply one when creating, a UUID is generated.

Create a connection

For OAuth providers, the easiest path is the connect flow. To store credentials directly:

POST /api/v1/connections
API-Key: sk_...
 
{
  "provider_config_key": "github",
  "connection_id": "acme",
  "credentials": { "access_token": "ghp_..." }
}

Read connections

GET  /api/v1/connections/{provider_config_key}/{connection_id}
GET  /api/v1/connections?provider_config_key=github&skip=0&limit=50

List responses include a total count in the X-Total-Count header. Each connection carries a computed status — active, expired, degraded, or error — so you can surface health.

Test a connection

POST /api/v1/connections/{provider_config_key}/{connection_id}/test

Returns { "status": "ok" | "error", "health": "...", "checked_at": "...", "error"?: "..." }.

Update metadata and credentials

PATCH /api/v1/connections/{provider}/{connection_id}/metadata     { "metadata": { ... } }
PATCH /api/v1/connections/{provider}/{connection_id}/credentials  { "credentials": { ... } }

Delete

DELETE /api/v1/connections/{provider_config_key}/{connection_id}

Connections are soft-deleted. See also managing multiple accounts and importing existing connections.