Connections API

Connections represent authenticated credentials for third-party services. Each connection stores an encrypted set of credentials (API key, OAuth2 tokens, or custom auth) for a specific piece. The value field is encrypted at rest using AES-256.

List Connections

Retrieve all connections for the authenticated organization.

GET /api/v1/connections

Query parameters

Example request

curl https://your-api.example.com/api/v1/connections?pieceName=slack \
  -H "Authorization: Bearer wvz_your_api_key"

Example response

{
  "data": [
    {
      "id": "conn_abc123",
      "pieceName": "slack",
      "displayName": "Acme Slack Workspace",
      "externalId": "user-42",
      "projectId": null,
      "status": "ACTIVE",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ]
}

The value field is never returned in list responses. Use the get endpoint to retrieve a single connection with its decrypted value (for authorized callers).

Create Connection

Create a new connection for a piece.

POST /api/v1/connections

Request body

Example: API key auth

curl -X POST https://your-api.example.com/api/v1/connections \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pieceName": "openai",
    "displayName": "Production OpenAI Key",
    "value": {
      "type": "SECRET_TEXT",
      "secret_text": "sk-proj-abc123..."
    }
  }'

Example: OAuth2 connection

curl -X POST https://your-api.example.com/api/v1/connections \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pieceName": "slack",
    "displayName": "Acme Slack",
    "value": {
      "type": "OAUTH2",
      "access_token": "xoxb-...",
      "refresh_token": "xoxr-...",
      "token_type": "bot",
      "scope": "chat:write,channels:read"
    },
    "externalId": "user-42"
  }'

Example response

{
  "id": "conn_def456",
  "pieceName": "slack",
  "displayName": "Acme Slack",
  "externalId": "user-42",
  "projectId": null,
  "status": "ACTIVE",
  "createdAt": "2025-01-15T10:35:00Z",
  "updatedAt": "2025-01-15T10:35:00Z"
}

Get Connection

Retrieve a single connection by ID.

GET /api/v1/connections/:id

Example request

curl https://your-api.example.com/api/v1/connections/conn_def456 \
  -H "Authorization: Bearer wvz_your_api_key"

Example response

{
  "id": "conn_def456",
  "pieceName": "slack",
  "displayName": "Acme Slack",
  "externalId": "user-42",
  "projectId": null,
  "status": "ACTIVE",
  "createdAt": "2025-01-15T10:35:00Z",
  "updatedAt": "2025-01-15T10:35:00Z"
}

Delete Connection

Permanently delete a connection. Any triggers or MCP servers using this connection will lose access to the third-party service.

DELETE /api/v1/connections/:id

Example request

curl -X DELETE https://your-api.example.com/api/v1/connections/conn_def456 \
  -H "Authorization: Bearer wvz_your_api_key"

Example response

{
  "success": true
}

External ID

The externalId field allows you to associate a connection with an end user in your system. This is useful when building multi-tenant integrations where each of your users has their own credentials.

• The combination of orgId + pieceName + externalId must be unique. You cannot create two Slack connections with the same external ID within one organization.
• When executing actions or enabling triggers, you can pass externalId instead of connectionId to automatically resolve the correct connection for that user.

Encryption

All connection values are encrypted at rest using AES-256-GCM. The encryption key is derived from the ENCRYPTION_KEY environment variable. Decryption happens only at the moment a connection is used to authenticate an API call to the third-party service.

The encrypted value is never returned in API responses. Only metadata (piece name, display name, status) is included in responses.

Connection Policies

Connection behavior can be configured per piece per project using connection policies. There are four policy types: