Multi Org Strategy

Use this skill when evaluating whether to use multiple Salesforce production orgs, designing how those orgs will exchange data, reviewing an existing multi-org architecture for hidden risks, or troubleshooting cross-org integration failures. This skill addresses the structural decision layer — it does not replace role-specific skills for building individual integrations, configuring Named Credentials, or setting up SSO providers.

Before Starting

• What is the actual driver? Regulatory data residency, M&A, distinct business unit with no data overlap, or has "we should have separate orgs" become an assumption without a justification? The answer shapes everything.
• Is this really a sandbox question? Development, QA, and UAT isolation is handled by sandboxes — not by separate production orgs. If the conversation is about dev/prod separation, use the sandbox-strategy skill instead.
• What data needs to cross org boundaries? If the answer is "most of it," that is a signal that multiple orgs may be the wrong call.
• Who manages user access across the orgs? Deactivation, permission changes, and onboarding must be replicated independently in each org unless an external IdP handles provisioning.

Core Concepts

Single Org Is the Default Recommendation

Salesforce architects strongly recommend single-org architecture unless a specific, documented requirement justifies multiple orgs. A single org eliminates:

• Cross-org data synchronization overhead (no API calls, no sync jobs, no eventual consistency risk)
• User management duplication (one user record, one deactivation action, one permission set assignment)
• Licensing complexity (licenses belong to one org; none are shared across orgs)
• Governor limit exposure from cross-org callouts (each callout consumes limits on both sides)
• Deployment coordination across two or more separate release pipelines

When requirements can be satisfied inside a single org using standard multi-tenancy features (Sharing Rules, Record Types, Permission Sets, Business Units in Marketing Cloud), a single org is always the lower-risk, lower-cost path.

When Multiple Production Orgs Are Justified

Multiple production orgs are justified only when a single org structurally cannot satisfy the requirement:

What Multiple Orgs Do NOT Solve

• Development vs. production isolation: That is sandboxes. Use sandboxes.
• Performance problems in a single org: Multiple orgs do not redistribute governor limits in a meaningful way; they duplicate them.
• Large data volume concerns: LDV strategies (indexes, archival, Big Objects, skinny tables) are the correct approach inside a single org.

Mode 1: Design a Multi-Org Strategy from Scratch

Use this mode when a new org topology is being designed before any build begins.

Step 1 — Confirm the multi-org justification

Ask the client or stakeholder to provide a written requirement that a single org cannot satisfy. If they cannot articulate one, default to single-org architecture. Document the justification in the architecture decision record.

Step 2 — Select an org topology

Option A: Single Hub Org All business processes live in one production org. Cross-system data exchange is handled via Salesforce APIs to external systems (non-Salesforce). This is the preferred end state.

Option B: Hub-and-Spoke One "hub" org aggregates and coordinates data from multiple "spoke" orgs. The hub holds canonical records or reporting aggregates. Spoke orgs hold domain-specific data.

• Hub-to-spoke and spoke-to-hub data flow uses REST API or Bulk API 2.0 — not Salesforce-to-Salesforce.
• Salesforce Connect (External Objects) in the hub org can surface spoke data as virtual records without full replication.
• The hub org's integration user must have a Connected App in each spoke org with appropriate OAuth scopes.

Option C: Peer-to-Peer Two or more orgs exchange data directly with no central coordinator. This topology has the highest complexity and is the hardest to govern. Avoid it unless the orgs have truly independent data domains with only occasional cross-org lookups.

Step 3 — Design cross-org data exchange

For each org pair that must exchange data:

1. Choose the integration mechanism:

   • REST API: preferred for record-by-record or small-batch synchronous exchange
   • Bulk API 2.0: preferred for large-volume nightly or periodic sync jobs (millions of records)
   • Salesforce Connect (External Objects): preferred for near-real-time cross-org lookup without full replication; data is queried on-demand via OData 2.0/4.0 adapter or a custom adapter

2. Authenticate with Named Credentials:

   • Create a Connected App in the target org (the org being called).
   • Create a Named Credential in the calling org that stores the OAuth 2.0 JWT Bearer credentials for that Connected App.
   • Never store client secrets, access tokens, or refresh tokens in Custom Settings, Custom Metadata, or Apex code.
   • Use the JWT Bearer flow (server-to-server, no user interaction) for scheduled or automated cross-org calls.

3. Define data ownership:

   • Each record has exactly one system of record. The owning org creates and updates it. Other orgs read or receive copies.
   • Avoid bidirectional sync unless absolutely required; bidirectional sync requires conflict resolution logic and has no native Salesforce support.

Step 4 — Design identity and SSO

• Use an external IdP (Okta, Azure AD, Ping) as the SSO provider for all orgs.
• Configure each Salesforce org as a separate Service Provider (SP) registered with the same IdP.
• Users authenticate once against the IdP and receive a SAML assertion for the target org.
• User provisioning (SCIM) from the IdP to each org automates account creation and deactivation.
• Do not rely on manual admin processes to deactivate users across orgs — deactivation in one org does not deactivate in another.

Step 5 — Account for licensing

• Each Salesforce production org requires its own license allocation.
• Licenses are not shared across orgs. A user who needs access to two orgs requires two license seats.
• Validate the license implications with the Salesforce Account team before finalizing the topology.

Mode 2: Review an Existing Multi-Org Architecture

Use this mode when reviewing an inherited or in-flight multi-org design for risks and improvement opportunities.

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
4. Validate — run the skill's checker script and verify against the Review Checklist below
5. Document — record any deviations from standard patterns and update the template if needed

Review Checklist

• Justification is documented: Each production org has a written requirement that a single org cannot satisfy. If not, consolidation should be evaluated.
• No Salesforce-to-Salesforce (S2S) in active use for new integrations: S2S is a legacy feature. Any active S2S connections should have a migration plan to REST API + Named Credentials.
• Named Credentials used for all cross-org callouts: No hard-coded org IDs, client secrets, or access tokens in Apex, Custom Settings, or Custom Metadata.
• Connected Apps scoped correctly: Each Connected App grants the minimum required OAuth scopes. Avoid full scope.
• Data ownership is defined: Each record type has exactly one system of record. Bidirectional sync is explicitly documented and has conflict resolution logic.
• User deactivation process spans all orgs: When a user is offboarded, the process covers every org they have access to (or the IdP SCIM push handles it automatically).
• Governor limit budget is understood: Cross-org callouts consume Apex callout limits (100 callouts per transaction), HTTP limits, and SOQL limits on both sides. The design should account for peak load.
• External Objects are used for read-only cross-org lookup: If an org only needs to display data from another org without owning it, Salesforce Connect is lower overhead than full record replication.
• Bulk API 2.0 used for high-volume sync: Nightly or periodic sync of more than a few thousand records should use Bulk API 2.0, not REST API row-by-row.

Mode 3: Troubleshoot Multi-Org Integration Problems

Use this mode when cross-org integrations are failing, hitting limits, or behaving inconsistently.

Diagnostic Table

Integration Pattern Decision Matrix

Salesforce-to-Salesforce (S2S) — Legacy Feature Notice

Salesforce-to-Salesforce is a native Salesforce feature that allows records to be published from one org and subscribed in another. It exists and continues to function, but Salesforce considers it a legacy integration approach.

Do not use S2S for new integrations. Reasons:

• S2S uses SOAP API under the hood, consuming API call limits on both orgs for every record exchange.
• It does not scale to high record volumes — each record publication is a separate API transaction.
• It offers no support for modern OAuth patterns, Named Credentials, or JWT Bearer flows.
• It creates tight coupling between orgs with no abstraction layer for error handling or retry logic.

Migration path from S2S: Replace with a REST API integration authenticated via Named Credentials (JWT Bearer flow) in the calling org, with a Connected App in the target org. For high volume, use Bulk API 2.0.

Related Skills

• integration/named-credentials-and-callouts — for Named Credential and Connected App configuration details
• architect/solution-design-patterns — for broader automation layer decisions
• security/ skills — for OAuth scope design and IP range restrictions on Connected Apps
• data/ skills — for LDV design within a single org (an alternative to multi-org for data volume concerns)