Connection Policies

Connection policies control how credentials are shared and resolved across users and projects within an organization. Each piece in each project can have its own policy, giving you fine-grained control over which connections are used when executing actions or enabling triggers.

Policies answer the question: “When a user executes an action for this piece in this project, which connection should Weavz use?”

The Four Policy Types

ENFORCED_ORG

The organization administrator sets a single connection for the piece, and all users in the organization use that connection. Individual users cannot override it.

How it works:

1. An org admin creates a connection for the piece (e.g. a shared Slack workspace)
2. The admin sets the policy to ENFORCED_ORG and selects the connection
3. When any user in the org executes an action for that piece, the enforced connection is used automatically
4. Users do not see a connection selector for this piece — it is pre-resolved

Best for:

• Shared company accounts (e.g. a team Slack workspace, company GitHub org)
• Service accounts where you want centralized control (e.g. a shared HubSpot CRM instance)
• Compliance scenarios where credentials must be managed by an administrator

Example:

PUT /api/v1/policies
{
  "pieceName": "slack",
  "projectId": null,
  "type": "ENFORCED_ORG",
  "connectionId": "conn_shared_slack"
}

ENFORCED_PROJECT

Similar to ENFORCED_ORG, but scoped to a specific project. A project administrator sets the connection, and all users working within that project use it. The same piece can have different enforced connections in different projects.

How it works:

1. A project admin creates a connection and sets the policy to ENFORCED_PROJECT for a specific project
2. Users executing actions within that project automatically use the enforced connection
3. The same piece in a different project can have a different policy or connection

Best for:

• Multi-environment setups (e.g. staging vs. production Stripe keys in different projects)
• Client-specific projects where each client has their own service credentials
• Team projects where a specific set of credentials should be used by all team members

Example:

PUT /api/v1/policies
{
  "pieceName": "stripe",
  "projectId": "proj_production",
  "type": "ENFORCED_PROJECT",
  "connectionId": "conn_stripe_prod"
}

USER_REQUIRED

Each user must provide their own connection for the piece. There is no shared or default connection. If a user attempts to execute an action without having created their own connection, the request fails with a CONNECTION_REQUIRED error.

How it works:

1. The policy is set to USER_REQUIRED for the piece
2. Each user must create their own connection (e.g. connect their personal GitHub account)
3. When a user executes an action, Weavz resolves their personal connection based on their user ID
4. If the user has not created a connection, the request fails with a clear error message

Best for:

• Personal accounts that should not be shared (e.g. each developer's GitHub token)
• Privacy-sensitive integrations (e.g. personal email, calendar)
• Scenarios where audit trails must trace actions to individual users
• End-user facing products where each customer connects their own accounts

Example:

PUT /api/v1/policies
{
  "pieceName": "github",
  "projectId": "proj_dev_tools",
  "type": "USER_REQUIRED",
  "connectionId": null
}

USER_WITH_DEFAULT

The organization provides a default connection that all users share, but individual users can override it with their own connection. If a user has not created a personal connection, the default is used.

How it works:

1. An admin creates a default connection and sets the policy to USER_WITH_DEFAULT
2. Users who have not created their own connection automatically use the default
3. Users who want to use their own credentials create a personal connection, which takes priority over the default

Best for:

• Teams with a shared account but where some members need personal credentials (e.g. a team Notion workspace where some users have admin tokens)
• Gradual rollout scenarios where you start with a shared connection and let users migrate to personal ones over time
• Development teams where a shared sandbox account is the default but production deployments use personal tokens

Example:

PUT /api/v1/policies
{
  "pieceName": "notion",
  "projectId": null,
  "type": "USER_WITH_DEFAULT",
  "connectionId": "conn_team_notion"
}

Policy Resolution Order

When Weavz needs to resolve a connection for an action or trigger, it follows this priority chain:

1. Explicit connection ID: If the request specifies a connectionId, that connection is used directly regardless of any policy.
2. External ID: If the request specifies an externalId, Weavz resolves the connection by external ID.
3. Project-level policy: If the request is scoped to a project and a policy exists for the piece in that project, it is applied.
4. Org-level policy: If no project-level policy exists, the org-level policy for the piece is applied.
5. Default behavior: If no policy is configured, the behavior depends on whether the action requires authentication. If it does, the user must provide a connection explicitly.

Configuring Policies

Via Dashboard

Navigate to Settings in the sidebar, then select the Policies tab. You will see a list of pieces with their current policy for each project. Click on a piece to change its policy and select the default connection (if applicable).

Via REST API

# Set or update a policy
PUT /api/v1/policies
{
  "pieceName": "slack",
  "projectId": "proj_abc",
  "type": "ENFORCED_PROJECT",
  "connectionId": "conn_xyz"
}

# Get policies for a project
GET /api/v1/policies?projectId=proj_abc

# Get all org-level policies
GET /api/v1/policies

Policy Comparison

Multi-Tenant Patterns

Connection policies are particularly powerful for multi-tenant applications. Here are some common patterns:

SaaS Platform with Customer Integrations

You are building a SaaS product where each customer connects their own Slack workspace. Use USER_REQUIRED for Slack and create connections with external IDs mapping to your customer IDs. Each API call includes the customer's external ID, and Weavz resolves the correct connection.

Internal Tool with Shared Services

Your team uses a shared Jira instance and shared Slack workspace, but each developer has their own GitHub token. Use ENFORCED_ORG for Jira and Slack, and USER_REQUIRED for GitHub.

Agency Managing Multiple Clients

You manage integrations for multiple clients, each in their own project. Use ENFORCED_PROJECT for each piece in each project, pointing to the client-specific credentials. Team members working across projects automatically use the correct credentials for each client.

Related

• Connections — How connections are created, encrypted, and managed
• MCP Servers — How policies interact with MCP tool invocations