Multi‑Org Strategy (Region × Project)

This guide outlines a practical approach to creating and operating multiple Amigo organizations (tenants) by region and project. Use this when you have disjoint user populations (e.g., clinical cohorts, product lines) and/or region‑specific residency requirements.

Why Multiple Orgs

• Data residency and latency: Keep user data and traffic in‑region.

• Strict isolation: Separate cohorts (e.g., 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/rollback changes per org.

Naming Convention

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

• <base>: Company/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:

  • US (N. Virginia, us‑east‑1) → useast

  • EU (Frankfurt, eu‑central‑1) → eucentral

  • AU (Sydney, ap‑southeast‑2) → apsoutheast

Constraints

• Org IDs allow letters and hyphens only; length 4–20.

• Prefer lowercase for readability and consistency.

• Avoid reserved or generic names (see Create Organization errors for reserved IDs).

Examples:

• acme-women-a-useast

• acme-men-b-eucentral

• acme-trials-apsoutheast

Tip: If you need finer granularity (e.g., multiple projects in the same region), extend <project> (for example, women-a, 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 (requires the provisioning header and permissions):

Create an organization

put

https://api.amigo.aihttps://internal-api.amigo.aihttps://api-eu-central-1.amigo.aihttps://api-ap-southeast-2.amigo.aihttps://api-ca-central-1.amigo.ai

/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, [email protected], 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.
• Role:CreateRole for the default roles to create for each organization.
• User.InviteUser for [email protected].
• The authenticated user must have greater or equal privileges than DefaultSuperAdministratorRole, which effectively means it must take the DefaultSuperAdministratorRole as well.

Authorizations

Bearer-Authorization & Bearer-Authorization-Organization

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

application/json

org_namestring · min: 1Required

A human friendly name of the organization.

titlestring · min: 1Required

An advertising tagline for the services offered by this organization.

main_descriptionstring · min: 1Required

A description of the services offered by this organization that is displayed on the login page for the Amigo frontend for this organization.

sub_descriptionstring · min: 1Required

Additional descriptions of the services offered by this organization that is displayed below main_description in a smaller font.

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.

signup_page_headshotstring · base64Required

An image of the main persona of the organization that is displayed on the signup page for this organization in base64 encoded bytes of a PNG image of size at least 292 * 400 pixels and aspect ratio 0.73. If not specified, a default headshot is used.

onboarding_instructionsstring[]Required

A list of markdown text that's displayed during the onboarding flow of this organization. Each entry corresponds to a page in the onboarding flow.

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

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/

HTTPcURLJavaScriptPython

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: 517

{
  "org_name": "text",
  "title": "text",
  "main_description": "text",
  "sub_description": "text",
  "user_dimensions": [
    {
      "description": "text",
      "tags": [
        "text"
      ]
    }
  ],
  "logo": "text",
  "square_logo": "text",
  "favicon": "text",
  "signup_page_headshot": "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"
    ]
  },
  "onboarding_instructions": [
    "text"
  ],
  "azure_devops_team_name": "text"
}

{
  "org_id": "text"
}

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; avoid cross‑org role assignments.

• Invite users to the specific org(s) they belong to; do not 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 (e.g., 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, e.g.:

  • acme-women-a-useast-staging

  • acme-women-a-useast-prod

Start with staging and production per region × 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; address regressions without impacting 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

• Core API → Tools

• Best Practices → Version Sets & Promotion