> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/operations/devops/multi-org-tenancy.md).

# Multi-Org Strategy (Region x Project)

This guide outlines a practical approach to creating and operating multiple Amigo organizations (tenants) by region and project. Reach for it when you have disjoint user populations (clinical cohorts, product lines) or region-specific residency requirements.

## Why Multiple Orgs

* **Data residency and latency**: keep user data and traffic in-region.
* **Strict isolation**: separate cohorts (for example, Women-A vs Men-B) and lines of business.
* **Governance boundaries**: independent roles, audit trails, and promotion controls per org.
* **Safer operations**: limit blast radius; roll out and roll back changes per org.

## Naming Convention

Use a consistent postfix pattern: `<base>-<project>-<region-tag>`

* `<base>`: company or program slug (letters only), e.g., `acme` or `acmehealth`.
* `<project>`: cohort or product slug, e.g., `women-a`, `men-b`.
* `<region-tag>`: alphabetic tag for the region of the org (letters only). Recommended values:

  * US East -> `useast`
  * Canada Central -> `cacentral`
  * EU Central -> `eucentral`
  * Asia-Pacific -> `apsoutheast`

  This list is illustrative - see [Regions & Endpoints](/developer-guide/getting-started/regions-and-endpoints.md) for the authoritative region list.

```mermaid
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#D4E2E7", "primaryTextColor": "#100F0F", "primaryBorderColor": "#083241", "lineColor": "#575452", "textColor": "#100F0F", "clusterBkg": "#F1EAE7", "clusterBorder": "#D7D2D0"}}}%%
graph TB
    Company[Amigo Platform]
    Company --> Base1[acme]
    Base1 --> Project1[women-a]
    Base1 --> Project2[men-b]
    Project1 --> Region1[useast]
    Project1 --> Region2[eucentral]
    Region1 --> Env1[acme-women-a-useast-prod]
    Region1 --> Env2[acme-women-a-useast-staging]
    Region2 --> Env3[acme-women-a-eucentral-prod]
    Region2 --> Env4[acme-women-a-eucentral-staging]
    style Env1 fill:#DDE3DB,stroke:#2c3827,color:#100F0F
    style Env2 fill:#F0DDD9,stroke:#AA412A,color:#100F0F
    style Env3 fill:#DDE3DB,stroke:#2c3827,color:#100F0F
    style Env4 fill:#F0DDD9,stroke:#AA412A,color:#100F0F
```

{% hint style="info" %}
Constraints

* Org IDs allow letters and hyphens only, and must be 4-20 characters long.
* Prefer lowercase for readability and consistency.
* Avoid reserved or generic names. The Create Organization endpoint rejects reserved organization IDs with a `400` error.
  {% endhint %}

Examples:

* `acme-women-a-useast`
* `acme-men-b-eucentral`
* `acme-trials-apsoutheast`

Tip: if you need finer granularity (for example, multiple projects in the same region), extend `<project>` (such as `women-a` and `women-a2`) while keeping the region tag unchanged.

## Region Selection

* Create a separate org per region to satisfy data residency and performance goals.
* Use the region's base URL for all API calls and SDK `baseUrl` settings. See [Regions & Endpoints](/developer-guide/getting-started/regions-and-endpoints.md) for current regional hosts.

## Creating Organizations

Provision each org with a unique, region-specific ID following the naming convention above. Use the Create Organization API, which requires the provisioning header and permissions.

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/organization/" method="put" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

Notes:

* This endpoint requires the cluster provisioning header and appropriate permissions. See the OpenAPI details above for the exact header name.
* After creation, your org is addressable at `<org-id>.amigo.ai` for frontend access.

## Access and Roles

* Treat each org as a hard boundary for RBAC. Grant administrators per org and avoid cross-org role assignments.
* Invite users to the specific org or orgs they belong to. Don't share user identities across unrelated cohorts.
* Keep default roles as-is unless you have a clear need for custom roles.

## Services and Tools per Org

* Services and tools are org-scoped by design. Define only what a cohort needs inside that org.
* Tool publishing builds from the organization's team tools repository: test on a branch, then publish versions for that org.
* Deprecate unused tool versions to manage cost.

## Recommended Environments

* Minimum recommended: one staging org and one production org per region x project.
* Add more environments as your DevOps flow requires (for example, `dev`, `qa`, `pilot`, `perf`).
* Use separate orgs per environment to isolate data, configuration, and rollouts.
* Naming: append an environment suffix after the region tag for clarity. Examples:
  * `acme-women-a-useast-staging`
  * `acme-women-a-useast-prod`

{% hint style="info" %}
Start with staging and production per region x project. Add `dev`, `qa`, or other environments only as needed.
{% endhint %}

{% hint style="info" %}
Keep org IDs within the allowed character set and length limits.
{% endhint %}

## Deployment and Change Management

* Roll out changes per org; use versioned promotion and rollback where applicable.
* Monitor reliability and performance by org and version, and address regressions without affecting other orgs.

## Checklist

* Pick the target region; decide the `<region-tag>`.
* Define `<base>` and `<project>` slugs; confirm the total length is 20 characters or fewer.
* Create the org via the API with required headers and permissions.
* Configure services and publish tools for that org.
* Invite users and assign org-local roles.
* Validate end-to-end in the region; monitor and iterate.

## Related

* Getting Started > [Regions & Endpoints](/developer-guide/getting-started/regions-and-endpoints.md)
* Classic API > [Tools](/developer-guide/classic-api/core-api/tools.md)
* Best Practices > [Version Sets & Promotion](/developer-guide/operations/devops/version-sets-best-practices.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/operations/devops/multi-org-tenancy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.