# Multi‑Org Strategy (Region × 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 (N. Virginia, us-east-1) → `useast`
  * EU (Frankfurt, eu-central-1) → `eucentral`
  * AU (Sydney, ap-southeast-2) → `apsoutheast`

{% @mermaid/diagram content="%%{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 (see Create Organization errors for reserved IDs).
  {% 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 Getting Started → Regions & Endpoints 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 `x-mongo-cluster-name` header and appropriate permissions. See the OpenAPI details.
* 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.
* Publish tools in the team branch associated with the org's team; prefer `repo: "team"` for org-specific tools.
* Deprecate unused tool versions to manage cost.

## Recommended Environments

* Minimum recommended: one staging org and one production org per region × 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 × 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 total length ≤ 20.
* 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)
* Core 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.