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 a Slack bot token and a Slack user token.

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, such as `slack_bot`
`integrationAlias`	Execution, partials, dynamic properties, MCP tools	Selector for the configured alias
`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.

Use Cases

Slack Bot vs User — slack_bot for automated messages, slack_user for user-context messages
GitHub Org vs Personal — github_work for work repos, github_personal for personal repos
Multiple Google Accounts — google_marketing and google_engineering 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 slack_bot. 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 slack_user, and a different connection strategy.

bash

# Add Slack with alias "slack_bot"
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": "slack_bot",
    "connectionStrategy": "fixed",
    "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "enabledActions": ["send_channel_message"]
  }'
 
# Add Slack again with alias "slack_user"
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": "slack_user",
    "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: 'slack_bot',
  connectionStrategy: 'fixed',
  connectionId: 'c1d2e3f4-5678-90ab-cdef-1234567890ab',
  enabledActions: ['send_channel_message'],
})
 
// User connection
await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'slack',
  alias: 'slack_user',
  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="slack_bot",
    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="slack_user",
    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 "slack_bot"
await fetch(`https://api.weavz.io/api/v1/workspaces/${workspaceId}/integrations`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    integrationName: 'slack',
    alias: 'slack_bot',
    connectionStrategy: 'fixed',
    connectionId: 'c1d2e3f4-5678-90ab-cdef-1234567890ab',
    enabledActions: ['send_channel_message'],
  }),
})
 
// Add Slack again with alias "slack_user"
await fetch(`https://api.weavz.io/api/v1/workspaces/${workspaceId}/integrations`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    integrationName: 'slack',
    alias: 'slack_user',
    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 "slack_bot"
httpx.post(
    f"https://api.weavz.io/api/v1/workspaces/{workspace_id}/integrations",
    headers=headers,
    json={
        "integrationName": "slack",
        "alias": "slack_bot",
        "connectionStrategy": "fixed",
        "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
        "enabledActions": ["send_channel_message"],
    },
)
 
# Add Slack again with alias "slack_user"
httpx.post(
    f"https://api.weavz.io/api/v1/workspaces/{workspace_id}/integrations",
    headers=headers,
    json={
        "integrationName": "slack",
        "alias": "slack_user",
        "connectionStrategy": "per_user_with_fallback",
        "connectionId": "d2e3f4a5-6789-0abc-def1-234567890abc",
        "enabledActions": ["send_channel_message"],
    },
)

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: slack_bot, github-work, airtable_prod, google_eng

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
`slack_bot`	`send_channel_message`	`slack_bot__send_channel_message`
`slack_user`	`send_channel_message`	`slack_user__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.slack_bot.send_channel_message({
  channel: '#alerts',
  text: 'Automated alert!',
})
 
await weavz.slack_user.send_channel_message({
  channel: '#general',
  text: 'Message from user context',
})

The weavz_read_api tool returns separate TypeScript declarations for each alias:

text

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

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 'slack_bot' 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.