Multi-Org Strategy (Region x Project)

Create and operate multiple Amigo organizations by region and project for tenant isolation.

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 for the authoritative region list.

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.

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 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.

Create an organization

put

/v1/{organization}/organization/

Set up a new organization in the Amigo system. Specifically, it

creates a new organization within the Amigo Mongo database with the given details.
- Along with the new organization, 4 default roles are created:
  - DefaultUserRole.
  - DefaultAdministratorRole.
  - DefaultAmigoAdministratorRole.
  - DefaultSuperAdministratorRole.
- A super user, admin@amigo.ai, is created and granted the DefaultSuperAdministratorRole.
creates a new tenant in Google Identity Platform for users in this organization.
creates a new Route53 record, {org_id}.amigo.ai, that hosts the Amigo frontend for this organization.
creates a new domain, {org_id}.amigo.ai, on Vercel.

The x-mongo-cluster-name header is mandatory for this endpoint.

Permissions

This endpoint requires the following permissions:

Organization:CreateOrganization. for the organization to create.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-namestringRequired

The Mongo cluster name to perform this request in.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

org_namestring · min: 1Required

A human friendly name of the organization.

logostring · base64Required

A logo for the organization that will be displayed on the Amigo frontend for this organization, as well as all Amigo communications to users on behalf of the organization. Must be provided as base64 encoded bytes of a PNG image of aspect ratio 5:2 with minimum size 400 * 160 pixels.

square_logostring · base64Required

A square logo of the organization. Must be provided as base64 encoded bytes of a square PNG image of size at least 40 * 40 pixels.

faviconstring · base64Required

Favicon for the Amigo frontend for this organization. Must be provided as base64 encoded bytes of a square ICO image that's of size at least 40 * 40 pixels.

azure_devops_team_namestring · min: 1 · max: 20Required

The name of the Azure DevOps team to create (if it doesn't exist) for this organization. All orgs with the same Azure DevOps team name will share access to the same Azure DevOps resources, namely the source code for tools.

Pattern: ^[a-z-]+$

Responses

201

Succeeded.

application/json

org_idstringRequired

ID of the newly created organization. This is used to identify the organization that a resource belongs to in all Amigo endpoints.

400

The specified organization ID is reserved.

401

Invalid authorization credentials.

403

Missing required permissions.

409

Conflicts with existing organization with the same org_id, or a related operation is in progress.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 5 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

put/v1/{organization}/organization/

PUT /v1/{organization}/organization/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
x-mongo-cluster-name: text
Content-Type: application/json
Accept: */*
Content-Length: 386

{
  "org_name": "text",
  "user_dimensions": [
    {
      "description": "text",
      "tags": [
        "text"
      ]
    }
  ],
  "logo": "text",
  "square_logo": "text",
  "favicon": "text",
  "default_user_preferences": {
    "enable_response_recommendation": false,
    "preferred_language": "aaa",
    "conversations_visible_to_admins": true,
    "user_model_visible_to_admins": true,
    "timezone": "Africa/Abidjan",
    "audio_keyterms": [
      "text"
    ]
  },
  "azure_devops_team_name": "text"
}

{
  "org_id": "text"
}

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

Start with staging and production per region x project. Add dev, qa, or other environments only as needed.

Keep org IDs within the allowed character set and length limits.

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.

Getting Started > Regions & Endpoints
Classic API > Tools
Best Practices > Version Sets & Promotion

PreviousBest Practices

NextVersion Sets & Promotion

Last updated 4 days ago

Was this helpful?