Integration Aliases

Configure the same integration multiple times in a workspace and target each instance with aliases.

Integration aliases let you add the same integration to a workspace multiple times, each with its own connection strategy, default connection, enabled actions, and identity. This is useful when you need separate configured instances for the same service, such as an office Slack workspace and a customer-context Slack account.

The naming model is:

Primitive	Where it is set	Where it is used
`integrationName`	Integration catalog	Base app slug, such as `slack`
`alias`	Workspace integration setup	Stable configured instance name agents see, such as `office_slack`
`integrationAlias`	Execution, partials, dynamic properties, MCP tools	Selector field for the same alias concept
`workspaceIntegrationId`	Workspace integration response	Exact UUID selector when your backend has it

MCP servers sync workspace integrations automatically. Manual MCP tool aliases are still available for server-specific overrides, but the workspace integration alias is the primary primitive. In Code Mode, the alias becomes weavz.<alias>; in Tool Mode, it becomes the {alias}__{action} tool prefix.

Use Cases

Slack Bot vs User — office_slack for automated messages, customer_slack for user-context messages
GitHub Org vs Personal — work_github for work repos, personal_github for personal repos
Multiple Google Accounts — marketing_google and engineering_google with different OAuth connections
Staging vs Production — airtable_staging and airtable_prod pointing to different bases

Creating Aliased Workspace Integrations

Open your workspace

Navigate to the workspace that will own the configured integrations.

Add a workspace integration

Open Integrations and select the integration, such as Slack.

Set the alias

In the Alias field, enter a custom name like office_slack. This becomes the integrationAlias used by actions, partials, dynamic properties, and MCP tools.

Choose a connection

Select the connection to use for this alias (e.g., your bot token connection).

Repeat for additional aliases

Add the same integration again with a different alias, such as customer_slack, and a different connection strategy.

bash

# Add Slack with alias "office_slack"
curl -X POST https://api.weavz.io/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/integrations \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "alias": "office_slack",
    "connectionStrategy": "fixed",
    "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "enabledActions": ["send_channel_message"]
  }'
 
# Add Slack again with alias "customer_slack"
curl -X POST https://api.weavz.io/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/integrations \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "alias": "customer_slack",
    "connectionStrategy": "per_user_with_fallback",
    "connectionId": "d2e3f4a5-6789-0abc-def1-234567890abc",
    "enabledActions": ["send_channel_message"]
  }'

typescript

const workspaceId = '550e8400-e29b-41d4-a716-446655440000'
 
// Bot connection
await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'slack',
  alias: 'office_slack',
  connectionStrategy: 'fixed',
  connectionId: 'c1d2e3f4-5678-90ab-cdef-1234567890ab',
  enabledActions: ['send_channel_message'],
})
 
// User connection
await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'slack',
  alias: 'customer_slack',
  connectionStrategy: 'per_user_with_fallback',
  connectionId: 'd2e3f4a5-6789-0abc-def1-234567890abc',
  enabledActions: ['send_channel_message'],
})

python

workspace_id = "550e8400-e29b-41d4-a716-446655440000"
 
# Bot connection
client.workspaces.add_integration(
    workspace_id,
    integration_name="slack",
    integration_alias="office_slack",
    connection_strategy="fixed",
    connection_id="c1d2e3f4-5678-90ab-cdef-1234567890ab",
    enabled_actions=["send_channel_message"],
)
 
# User connection
client.workspaces.add_integration(
    workspace_id,
    integration_name="slack",
    integration_alias="customer_slack",
    connection_strategy="per_user_with_fallback",
    connection_id="d2e3f4a5-6789-0abc-def1-234567890abc",
    enabled_actions=["send_channel_message"],
)

typescript

const headers = {
  'Authorization': 'Bearer wvz_your_key',
  'Content-Type': 'application/json',
}
 
const workspaceId = '550e8400-e29b-41d4-a716-446655440000'
 
// Add Slack with alias "office_slack"
await fetch(`https://api.weavz.io/api/v1/workspaces/${workspaceId}/integrations`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    integrationName: 'slack',
    alias: 'office_slack',
    connectionStrategy: 'fixed',
    connectionId: 'c1d2e3f4-5678-90ab-cdef-1234567890ab',
    enabledActions: ['send_channel_message'],
  }),
})
 
// Add Slack again with alias "customer_slack"
await fetch(`https://api.weavz.io/api/v1/workspaces/${workspaceId}/integrations`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    integrationName: 'slack',
    alias: 'customer_slack',
    connectionStrategy: 'per_user_with_fallback',
    connectionId: 'd2e3f4a5-6789-0abc-def1-234567890abc',
    enabledActions: ['send_channel_message'],
  }),
})

python

import httpx
 
headers = {"Authorization": "Bearer wvz_your_key"}
workspace_id = "550e8400-e29b-41d4-a716-446655440000"
 
# Add Slack with alias "office_slack"
httpx.post(
    f"https://api.weavz.io/api/v1/workspaces/{workspace_id}/integrations",
    headers=headers,
    json={
        "integrationName": "slack",
        "alias": "office_slack",
        "connectionStrategy": "fixed",
        "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
        "enabledActions": ["send_channel_message"],
    },
)
 
# Add Slack again with alias "customer_slack"
httpx.post(
    f"https://api.weavz.io/api/v1/workspaces/{workspace_id}/integrations",
    headers=headers,
    json={
        "integrationName": "slack",
        "alias": "customer_slack",
        "connectionStrategy": "per_user_with_fallback",
        "connectionId": "d2e3f4a5-6789-0abc-def1-234567890abc",
        "enabledActions": ["send_channel_message"],
    },
)

Full workspace-integration fields are in the Workspace Integrations API. Omit alias to use the integration name, omit enabledActions to expose all actions, and use displayName, settings, or sortOrder when those should affect dashboard, MCP, or generated surfaces.

Naming Rules

Aliases must follow these rules:

Format: lowercase letters, numbers, hyphens, and underscores only (/^[a-z][a-z0-9_-]*$/)
Length: maximum 64 characters
Must start with a lowercase letter
Consistent mapping: each alias in a workspace should represent one configured integration instance with a clear purpose

Valid examples: office_slack, support_slack_bot, customer_gmail, billing_stripe, work_github

Avoid vague aliases such as default, prod, or slack2. They work syntactically, but agents have less context when a workspace contains more than one configured account. Prefer underscores in examples because they stay readable in both JavaScript namespaces and MCP tool names.

Invalid examples: Slack_Bot (uppercase), 123slack (starts with number), slack bot (spaces)

Tool Naming with Aliases

In TOOLS mode, tool names use the alias instead of the integration name:

Alias	Action	Tool Name
`office_slack`	`send_channel_message`	`office_slack__send_channel_message`
`customer_slack`	`send_channel_message`	`customer_slack__send_channel_message`
`github_work`	`create_issue`	`github_work__create_issue`

Without an alias, the tool name defaults to using the integration name (e.g., slack__send_channel_message).

Code Mode with Aliases

In CODE mode, aliases create separate namespaces under weavz.*:

javascript

// With aliases, each has its own namespace
await weavz.office_slack.send_channel_message({
  channel: '#alerts',
  text: 'Automated alert!',
})
 
await weavz.customer_slack.send_channel_message({
  channel: '#general',
  text: 'Message from user context',
})

The weavz_read_api tool returns separate TypeScript declarations for each alias. When an agent needs more than one alias, it can request them together with aliases: [...]:

text

AI Agent calls: weavz_read_api({ alias: "office_slack" })
 
Returns:
  declare namespace weavz {
    namespace office_slack {
      function send_channel_message(input: {
        channel: string;
        text: string;
      }): Promise<{ ok: boolean }>;
    }
  }

text

AI Agent calls: weavz_read_api({ aliases: ["office_slack", "customer_slack"] })

Alias Conflicts

Within a workspace, an alias should identify exactly one configured integration instance. Creating the same alias twice, or using one alias for two different base integrations, is rejected.

For advanced manual MCP tools, server-local aliases follow the same principle. If you try to add a manual tool with an alias already associated with a different integration on the same server, you get a 409 ALIAS_CONFLICT error:

json

{
  "error": "Alias 'office_slack' is already associated with integration 'slack' on this server",
  "code": "ALIAS_CONFLICT"
}

This prevents confusion: one alias should map to one configured integration in a workspace, and one integration per server when you use manual tool overrides.

Default Behavior

When no custom alias is provided for a workspace integration, the integration name itself is used as the alias. That means slack produces slack__send_channel_message in Tool Mode and weavz.slack in Code Mode.