Choose Your Tenancy Model

When one organization runs several sites, brands, regions or channels, the first architecture decision is how many Agility instances to use. This page helps you decide between one instance with several sitemaps and several instances, and explains how that choice interacts with locales, permissions, API keys, webhooks and preview.

Using Agility for Multiple Sites describes each option. This page is about choosing.

The options

Option	What it is	Typical fit
One instance, one sitemap	One site	A single website, even with several locales
One instance, several sitemaps	Each site is a sitemap with its own pages and domains, sharing models, components and content	Sub-brands, microsites or regional sites run by one team
One instance, page folders	Each site is a folder in one sitemap, on one domain and one codebase	Microsites under a main domain, such as /events or /careers
Several instances	Each site is fully separate in content, assets, editors, security and workflow	Brands or regions with separate teams, rules or data
Several instances plus a content hub	Separate site instances, plus one instance holding the content every site shares	Separate teams that still share products, locations or legal text

Using a locale to represent a different site is possible, but locales are not designed for it. Use locales for languages and regions of the same site. See Choosing a Localization Strategy.

How the options compare

	One instance, several sitemaps	Several instances
Models, components, page models	Shared	Defined per instance. Keep them in step yourself, for example with the CLI
Content	One pool, organized by folders and naming	Separate per instance
Reusing content across sites	Link to it directly	Read it from the other instance through its API, or copy it
Editors see	Every page and content list in the instance, though permissions limit what they can open or change	Only the instances they have access to
Permissions	Roles per instance, raised per page, content list and asset folder	Separate roles per instance
Workflow and approvals	Set per page and content list	Fully separate per instance
API keys	One set: a fetch key reads all published content in the instance	Separate keys per instance
Webhooks	One set for the instance; your endpoint works out which site is affected	Separate per instance
Domains	Mapped per sitemap	Per instance
Preview	A preview deployment per sitemap	Per instance
Data region	One region for all sites	Chosen per instance, so sites can live in different regions
Deployment	One codebase can serve every sitemap	A separate deployment per instance
Licensing	Additional sitemaps can be added to a subscription	Each instance needs its own subscription

Licensing details change. Check the impact with Agility before you decide.

Decide in five questions

Work through these in order. The first "yes" that points to separate instances usually settles it.

1. Must one site's team be unable to see the other's content? Users with access to an instance can see all its pages and content listed, even where permissions stop them opening it. If teams must not see each other's work at all, use separate instances.
2. Must one site's published content be unreadable with another site's API key? A fetch key reads every published item in its instance; the API is not scoped per sitemap. If that is a problem, use separate instances.
3. Must sites keep their data in different regions? The data region is set per instance. Sites with different residency requirements need separate instances. See Data Residency & Data Regions.
4. Do the sites need different workflows, release schedules or administrators? Approvals can be set per page and per content list, but an instance has one set of administrators and settings. Very different governance points to separate instances.
5. Do the sites share most of their models, components and a lot of content? If yes, and nothing above ruled it out, use one instance with a sitemap per site. Sharing is direct, and one codebase serves every site.

If you chose separate instances but the sites still share content, add a content hub instance for that content. See Building a Content Hub.

How tenancy interacts with locales

Tenancy and localization are separate decisions that stack:

• Locales live inside an instance. Every sitemap in an instance can use the instance's locales. Connected copies, bulk copy to other locales and the translation tools all work between locales of one instance, not across instances.
• One instance, sitemaps per region. A regional site can be a sitemap in a shared instance, with its own domain and the locales it needs.
• One instance per region. Each region gets its own instance and uses locales inside it for that region's languages.

Choosing a Localization Strategy covers the field, page and instance levels in detail.

How tenancy interacts with permissions

Roles are assigned per instance. In a shared instance, you separate sites with item-level permissions:

• Give each site's editors a low instance role, such as Reader, then grant Editor or Publisher on that site's pages and content lists. Item-level permissions only add access; they can't take it away.
• Put each site's assets in its own folder and set folder security.
• Use Teams so each site's group of editors gets its roles in one step.

These controls limit what people can change, not what they can see listed. See Roles and Permissions Matrix and the "Regional and locale teams" recipe in Role Design Recipes.

Webhooks, keys and builds in a shared instance

• Webhooks fire for the whole instance. A page event carries a pageID, which belongs to one sitemap. A content event carries a contentID and referenceName, and that item can appear on any site. Clear the item's cache on every site that can use it. See Webhook Events and Payload Reference.
• Read each site's sitemap by its channel name (sitemap/flat/{channel}) and include the site in every cache key.
• Builds for several sites share one instance's API. Stagger builds and cache every read. See Handle Rate Limits and Outages Gracefully.

Changing your mind later

• From one instance to several: the CLI sync command copies models and content from a source instance to a target. Synced items get new content IDs on the target, and a blank target is the reliable case. Plan for links and IDs to change. See CLI - CI/CD Integration Guide.
• From several instances to one: move each site's content into the shared instance with the Management API, SDKs or CLI, then rebuild its pages in a new sitemap.
• Moving an instance to another region is possible but needs planning time and a statement of work.

Related

• Using Agility for Multiple Sites
• Reference Architecture: Multi-Brand and Multi-Site
• Choosing a Localization Strategy
• Roles and Permissions Matrix
• Building a Content Hub
• Reference Architectures