Use Multiple Accounts with Integration Aliases

Let one Handler work across accounts for the same integration, while keeping its existing connection in place.

On this page

If you run two Shopify stores, a Handler can work with both in one code tool execution — for example, comparing stock across the stores. Previously, a Handler could use only one connection to an integration at a time.

An integration alias is a name, such as us_store, that lets a code tool select a particular connection. You connect the accounts, give the Handler access, and explain the job. The Handler writes or updates the code tool; you do not need to write code yourself.

When to Use Aliases

Use aliases when one Handler needs to:

  • Compare information between accounts, such as stock for matching SKUs in two Shopify stores.
  • Produce a report covering several accounts, while identifying which account each result came from.
  • Make an authorised change across accounts, using a tool you have agreed on with the Handler.

If a Handler only needs one account, you do not need an alias. You can also keep accounts with separate Handlers if their work should stay separate.

Before You Start

This walkthrough keeps an existing UK store connection and adds a US store with the alias us_store. These are example names; use your own accounts.

A Handler’s primary connection is the account its code tools use when they do not name an alias. Keep the same primary so those tools continue reaching the same account. Additional connections are available to tools that explicitly select them.

You must be the Handler’s creator to change its connections, and the Handler must not be archived. You can edit aliases on your personal connections; workspace connections require a workspace admin.

1. Name the Additional Connection

In Handle Chat, open Integrations and select Shopify. Under Connections, find the US account. If it is not connected yet, choose Connect to add it first.

On that connection, choose Add alias, type us_store, then select the tick icon to save it. The icon’s label is Save alias. Renaming the connection’s display name is not the same as giving it an alias.

Alias editor before and after choosing Add alias. Static illustration, using an example alias.

Aliases start with a lowercase letter and contain only lowercase letters, digits, hyphens or underscores, with no spaces. Each alias can be up to 64 characters, and a connection can have up to 10 aliases. One meaningful alias is usually enough. The name must be unique for that integration across your workspace, including its members’ personal connections.

Adding an alias does not give a Handler access. Next, choose which Handler can use this connection.

2. Give the Handler Access Alongside Its Primary

Open Handlers → your Handler → Integrations and choose Add connection.

  1. Find the UK account in the picker. If it is marked Current primary, leave it unchanged.
  2. If nothing is marked Current primary for Shopify, the Handler may only be inheriting a default. Choose Use as primary for the same account it already uses, not the new US account. The picker closes; choose Add connection again to reopen it.
  3. On the US account, check that Aliases: us_store is shown, then choose Add alongside.
Shopify rows from the connection picker. Static illustration, using example store names.

Add alongside appears only when the Handler already has an explicit primary for that integration, the other connection has an alias, and it has not already been added. Choosing Use as primary for the US account would switch the default account instead.

Back in Connected integrations, the UK account remains Primary and the US account is listed with us_store. Repeat for any other accounts this Handler needs. Each Handler’s access is set separately.

3. Ask the Handler to Use Both Accounts

Tell the Handler what each alias refers to, what it should do, and which accounts it should read or change. For example:

Compare stock for matching SKUs in our UK and US Shopify stores. The UK store is your primary connection; the US store is us_store. Create or update a code tool that reads both stores in one run and reports each store’s stock separately. Do not change any products.

Adding a connection does not automatically update existing code tools. Ask the Handler to create or adapt the tool, run a read-only check, and confirm that the results identify the correct stores before using it for changes.

How the Handler uses it

You describe the task; the Handler handles the code. Inside a code tool, it can select the primary UK connection and the additional US connection like this:

const ukStore = sdks.shopify;
const usStore = sdks.get(
  "shopify",
  "us_store"
);

The Handler can discover its granted aliases with sdks.list("shopify"). This returns alias names, not connections to loop over dynamically. Both arguments to sdks.get must be string literals written into the tool, because the connections are prepared before the code runs. The Handler discovers the names, then writes the selected aliases into its tool.

Access and Permissions

An alias selects an account; it does not add permissions. Code-tool permissions apply to the integration, not separately to each alias. Give this Handler only the connections it needs, and review its Handler Permissions before allowing changes across accounts.

If the Handler cannot find an alias, check its spelling and that the connection appears in the Handler’s Connected integrations. Creating the alias on the Integrations page alone is not enough. Keep alias names stable: if you remove a name a tool uses, ask the Handler to update that tool.

See Manage Integrations for connecting accounts, and Handler Connected Integrations for managing a Handler’s access.