# Choose Your Tenancy Model

> Source: https://agilitycms.com/docs/developers/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](/docs/overview/using-agility-cms-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](/docs/developers/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](/docs/developers/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](/docs/owners-admins/data-residency-and-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](/docs/overview/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](/docs/developers/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](/docs/owners-admins/roles-and-permissions-matrix) and the "Regional and locale teams" recipe in [Role Design Recipes](/docs/owners-admins/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](/docs/developers/webhook-events-and-payloads).
- **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](/docs/developers/handle-rate-limits-and-outages).

## 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](/docs/developers/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](/docs/overview/using-agility-cms-for-multiple-sites)
- [Reference Architecture: Multi-Brand and Multi-Site](/docs/developers/reference-architecture-multi-brand)
- [Choosing a Localization Strategy](/docs/developers/choosing-a-localization-strategy)
- [Roles and Permissions Matrix](/docs/owners-admins/roles-and-permissions-matrix)
- [Building a Content Hub](/docs/overview/building-a-content-hub)
- [Reference Architectures](/docs/developers/reference-architectures)