Weavz

Connections

A connection in Weavz represents a set of encrypted credentials that allow the platform to authenticate with a third-party service on behalf of a user or organization. Connections are the foundation of every integration — before you can execute an action or listen for a trigger, you need a connection to the relevant service.

Authentication Types

Weavz supports three authentication schemes, matching the patterns used by the vast majority of third-party APIs.

OAuth2 with PKCE

The most common auth type for SaaS APIs. When a user creates an OAuth2 connection, Weavz launches a popup window that redirects to the service's authorization page. After the user grants access, the service redirects back to Weavz with an authorization code. Weavz exchanges this code for access and refresh tokens, encrypts them, and stores them in the database.

All OAuth2 flows use PKCE (Proof Key for Code Exchange) for security, even when the service does not strictly require it. This prevents authorization code interception attacks.

Key behaviors of OAuth2 connections:

  • Automatic token refresh: When an access token expires, Weavz uses the stored refresh token to obtain a new one transparently. The user does not need to re-authorize.
  • Scope management: Each piece defines the OAuth scopes it requires. The authorization URL includes these scopes so the user sees exactly what permissions are being requested.
  • Provider-specific handling: Some providers (e.g. Google, Microsoft) have non-standard OAuth implementations. Weavz handles these quirks internally per piece.

API Key

Many services use simple API key authentication. The user provides their API key (or token) through a form in the dashboard or via the REST API. Weavz encrypts and stores the key, then includes it in requests to the service (typically as a header or query parameter, depending on the piece's configuration).

Custom Auth

For services that use non-standard authentication (e.g. username/password, multi-field tokens, or proprietary auth schemes), pieces can define a custom auth schema. The dashboard renders a dynamic form based on this schema, and Weavz stores the encrypted values as a structured object.

Encryption

All connection credentials are encrypted at rest using AES-256encryption. The encryption key is derived from the ENCRYPTION_KEY environment variable, which must be a 32-byte hex string. Credentials are encrypted before being written to the database and decrypted only at the moment they are needed for an API call.

The encryption key never leaves the server. Each organization has an isolated encryption context.

Connection Lifecycle

A connection passes through several states during its lifetime:

  1. Creation: The user initiates the connection through the dashboard or API. For OAuth2, this triggers the authorization flow. For API keys, the user submits the key directly.
  2. Active: The connection is ready to use. Actions and triggers can reference it. OAuth2 tokens are refreshed automatically as needed.
  3. Refresh failure: If an OAuth2 token refresh fails (e.g. the user revoked access on the third-party side), the connection enters an error state. Actions using this connection will fail with a clear error message indicating that re-authorization is needed.
  4. Deletion: The user deletes the connection. All encrypted credentials are removed from the database. Active triggers using this connection are disabled.

Multi-Tenant Scoping

Connections are scoped at two levels to support multi-tenant applications:

Organization Scope

Every connection belongs to an organization. Users within the organization can use org-level connections based on their role and the configured connection policies.

Project Scope

Connections can optionally be scoped to a specific project within an organization. This is useful when different applications or environments need different credentials for the same service (e.g. a staging Slack workspace vs. a production one).

External IDs

Each connection can have an external ID — a string that maps the connection to a user or entity in your application. This is essential for multi-tenant use cases where each of your end-users has their own connection to a service.

For example, if your SaaS product lets each customer connect their own Slack workspace, you would create one Weavz connection per customer, each with the customer's ID as the external ID. When executing an action on behalf of that customer, you pass the external ID and Weavz resolves the correct connection.

// Creating a connection with an external ID
POST /api/v1/connections
{
  "pieceName": "slack",
  "externalId": "customer_123",
  "auth": {
    "type": "OAUTH2",
    "code": "...",
    "codeVerifier": "..."
  }
}

// Executing an action using the external ID
POST /api/v1/actions/execute
{
  "pieceName": "slack",
  "actionName": "send_message",
  "input": { "channel": "#general", "text": "Hello" },
  "externalId": "customer_123"
}

External IDs must be unique per piece per project (or per piece per organization if no project is specified). This constraint prevents accidental credential collisions.

Connection Resolution

When an action or trigger needs a connection, Weavz resolves it through a priority chain:

  1. Explicit connection ID: If the request includes a connectionId, that connection is used directly.
  2. External ID: If the request includes an externalId, Weavz looks up the connection by external ID, piece, and project scope.
  3. Connection policy: If neither is provided, Weavz uses the configured connection policy for that piece and project to determine which connection to use.

Managing Connections via API

The REST API provides full CRUD operations for connections:

# List connections
GET /api/v1/connections

# Get a specific connection (metadata only, credentials are never exposed)
GET /api/v1/connections/:id

# Create a connection
POST /api/v1/connections

# Delete a connection
DELETE /api/v1/connections/:id

Note that credentials are never returned in API responses. The GET endpoints return metadata (piece name, auth type, status, external ID) but not the decrypted secrets.

Related