Secure Connection Tenancy Migration Guide

Overview

As of the October 2026 release, every Secure Connection belongs to exactly one tenant:

• Administrators see and manage only the connections of the tenants they administer.
• Only people in a connection's tenant can be added as its permitted senders or permitted recipients.
• Users can share files only over the sending connections of their own tenant.
• Files that arrive over a receiving connection are placed in that connection's tenant.

Connections created before this release had no tenant. The upgrade puts all of them in the installation's default tenant. This guide explains how administrators move a connection that serves people in a different tenant, or in more than one tenant, by recreating it in the right tenant.

Who can do what

Connections are administered per tenant. On Zitadel the administrator is the organization administrator (customer_admin) of the connection's organization; on Identity Service v2 it is a Tenant Administrator of the connection's tenant. A Platform Administrator administers connections only in their own tenant: the platform role grants no access to another tenant's connections.

Action	Administrator of the connection's tenant	Administrator of another tenant
See and manage the connection	Yes	No
Create a connection in the tenant	Yes	No
Add permitted senders or recipients from the connection's tenant	Yes	No
Add permitted senders or recipients from any other tenant	No	No
Remove existing permitted senders or recipients from another tenant	Yes	No
Archive the connection	Yes	No

"Zitadel" means an installation without tenant management, where each Zitadel organization is a tenant. "Identity Service v2" means an installation with tenant management. See Administrators for the Identity Service v2 roles.

What the upgrade changes

• Every existing connection is placed in the default tenant. On Identity Service v2 this is the default tenant. On Zitadel it is the instance's default organization. Only its administrators see these connections now.
• Existing members from other tenants keep their access. Nobody is removed from a connection. A permitted sender or recipient in another tenant keeps their current access until an administrator removes them. The connection's member lists flag them as being in another tenant.
• No new members from other tenants. Adding someone outside the connection's tenant is refused.
• Sending connections are offered to their own tenant only. A permitted sender in another tenant no longer gets the connection when they share a file.
• New files land in the connection's tenant. Everything a receiving connection receives from now on is placed in the default tenant, even when its permitted recipients belong to another tenant. Files received before the upgrade stay where they are.

A connection whose members are all in the default tenant needs no action.

Which connections to recreate

Recreate a connection in the tenant it should belong to when:

• its permitted senders or permitted recipients belong to a tenant other than the default tenant; or
• it serves more than one tenant. Create one connection per tenant.

On a connection that serves several tenants, the members outside the default tenant are the ones to move. The connection itself can stay in the default tenant for its default-tenant members.

Before you start

For each connection you recreate, write down its current settings: object store, infosec settings, access type, onward sharing, whether a sending connection allows all users to share or only its permitted senders, tag rules or transformations, infosec schema mapping, and which members belong to which tenant. A new connection does not copy anything from the old one.

Recreate a connection

The steps are the same on both systems. Only who may do them differs; see On Zitadel and On Identity Service v2.

A sending connection

1. In the target tenant, add a sending connection with the settings you wrote down, including whether all users may share over it. A new sending connection allows only its permitted senders by default. Use a new Shared ID and Shared Secret.
2. Add the target tenant's people as its permitted senders, and recreate its tag rules.
3. Give the new Shared ID and Shared Secret to the partner's administrator. They add a matching receiving connection on their platform.
4. The target tenant's users share their files again over the new connection.
5. Clean up the old connection:
   • If it still serves people in the default tenant, remove the members you moved.
   • If nobody else uses it, unshare any files you want revoked, wait until the partner has processed the revocations, then archive it. Archiving stops synchronization, so a revocation that has not reached the partner yet is never delivered.

Use a fresh Shared ID

The Shared ID selects the folder in the outbox that a sending connection writes to. If the new connection reuses the old connection's Shared ID, both write their manifests and content into the same folder, and the partner's receiving connections cannot tell the two apart. Give the new connection a Shared ID that no other connection on the platform uses, and have the partner create a new receiving connection for it rather than editing the old one.

A receiving connection

Files that already arrived over a receiving connection cannot move to another tenant. The new connection receives the partner's files again, into the target tenant.

1. Get the Shared ID and Shared Secret of the partner's sending connection.
2. In the target tenant, add a receiving connection with that Shared ID and Shared Secret. It may use the same inbox as the old connection.
3. Add the target tenant's people as its permitted recipients, and recreate its transformations and infosec schema mapping.
4. Wait for the new connection to sync, and confirm the files arrived in the target tenant.
5. Clean up the old connection:
   • If it still serves people in the default tenant, remove the permitted recipients you moved.
   • If nobody else uses it, archive it.

warning

Archiving a receiving connection archives every file received over it, and revokes any onward shares made from those files. Make sure the target tenant's users have what they need from the new connection first.

On Zitadel

On Zitadel, an organization administrator (customer_admin) administers only the Zitadel organization they belong to. No Istari role can create or manage a connection in another organization.

Connection	Who recreates it
The old connection, in the default tenant	An organization administrator of the default organization
The new connection, in the target tenant	An organization administrator of the target organization

1. An organization administrator of the default organization writes down the old connection's settings and members. Only administrators of the default tenant can see it.
2. An organization administrator of the target organization creates the new connection there and adds that organization's people.
3. An organization administrator of the default organization removes the moved members from the old connection, or archives it.

If the target organization has no organization administrator, a Zitadel Org Owner of that organization grants customer_admin to one of its people; see Granting Admin Access.

On Identity Service v2

On Identity Service v2, a Tenant Administrator administers their own tenant. A Platform Administrator administers connections in their own tenant only, but can grant the Tenant Administrator role in any tenant.

Connection	Who recreates it
The old connection, in the default tenant	A Tenant Administrator of the default tenant
The new connection, in the target tenant	A Tenant Administrator of the target tenant

1. A Tenant Administrator of the default tenant writes down the old connection's settings and members. Only administrators of the default tenant can see it.
2. A Tenant Administrator of the target tenant creates the new connection there and adds that tenant's people.
3. A Tenant Administrator of the default tenant removes the moved members from the old connection, or archives it.

If the target tenant has no Tenant Administrator, a Platform Administrator grants the role to one of its people first; see Grant an administrator role.

Verification

• The new connection belongs to the target tenant, and every one of its permitted senders or recipients is in that tenant.
• No connection is still flagged as having members in another tenant, unless you chose to keep them.
• For a sending connection, the partner confirms the files arrived over the new connection.
• For a receiving connection, the files appear in the target tenant, and its permitted recipients can open them.

Getting Help

If you encounter issues during migration, contact your Istari Digital support representative.