A multi-tenant SaaS integration architecture is part product surface, part security boundary, and part distributed scheduler. Each customer connects a different account, grants different authority, selects objects and directions, and consumes a quota the provider may enforce at application, account, user, endpoint, or rolling-window level. One tenant's expired token, enormous backfill, poison record, or quota exhaustion must not stall other customers or expose their credentials and data.
The connector should be a shared, versioned capability with tenant-scoped configuration and work state, not a copied workflow per customer. Microsoft recommends standard formats and composable integration components, plus retry, circuit-breaker, and bulkhead patterns for outbound connections. OAuth supplies delegated or client authorization, but secure token storage, rotation, revocation, fair use, schema adaptation, and recovery remain application responsibilities. Design those responsibilities as first-class contracts before adding a catalog of providers.
Define a contract for every tenant connection
Represent a connection as tenant ID, provider, external account identity, authorization type, granted scopes, enabled objects, direction, field mapping version, synchronization mode, cursor or checkpoint, schedule, priority tier, data classification, owner, health state, and created or revoked times. Use an immutable connection ID in all work items and telemetry. A tenant may have several connections to the same provider, so provider name plus tenant is not a sufficient key.
Separate authorization from configuration. Completing an OAuth grant proves the authorization server issued tokens; it does not prove the expected external account, scopes, webhooks, objects, or permissions are usable. Run a post-connect verification that fetches safe account metadata and tests required operations. Show the tenant exactly which account and capabilities are active. Detect scope reduction and external deauthorization later. Never silently fall back to a broader shared credential when a tenant grant fails.
| Isolation surface | Tenant-scoped control | Shared component | Failure to prevent |
|---|---|---|---|
| Credentials | Envelope key, token family, access policy | Vault service | Cross-tenant token retrieval |
| Work | Queue key, cursor, priority, concurrency | Scheduler and workers | One backfill starves normal syncs |
| Quota | Budget and observed provider limits | Rate coordinator | One tenant consumes application allowance |
| Data | Staging namespace and idempotency keys | Mapping runtime | Rows or retries cross connection |
| Health | State, errors, pause, replay boundary | Operations console | Global pause for local failure |
Manage credentials as tenant assets
Store access tokens, refresh tokens, API keys, and client certificates in a secrets system encrypted with narrowly scoped workload access. Bind each secret reference to tenant and connection metadata outside application logs. Separate production and nonproduction credentials. Audit create, read by workload, refresh, rotate, revoke, and delete operations. Avoid presenting secret values after capture. For tenant-provided API keys, support overlap during rotation so a customer can verify a new key before the old one is removed.
Follow current OAuth security guidance for the flow in use. RFC 9700 updates OAuth 2.0 security practice, including redirect protection, token replay prevention, privilege restriction, and refresh-token considerations. Prefer authorization code with PKCE for user-mediated flows, exact redirect matching, state or stronger transaction binding, least privilege, and provider-supported sender-constrained tokens where justified. Refresh under a per-connection lock so concurrent workers do not race rotating refresh tokens. On invalid_grant, stop retry storms and move the connection to action-required.
Partition work and schedule fairly
Create work items with tenant ID, connection ID, provider, operation class, object or page, cursor version, attempt, earliest execution, deadline, cost estimate, and idempotency key. Partition queue and checkpoint state by connection. Use weighted fair scheduling so interactive changes, incremental syncs, and backfills receive intentional shares. Bound concurrency per connection, tenant, provider account, and provider application. A global FIFO queue allows one large customer to become everyone else's latency.
Apply backpressure before provider failure. Slow producers or defer low-priority backfills when queues, database writes, or provider budgets approach limits. Keep a reserve for token verification, webhooks, and customer-triggered actions. Isolate poison records after bounded attempts so one malformed object does not block a cursor forever. Support pause at connection, tenant, provider operation, and global emergency levels with documented precedence. Resuming should continue from durable checkpoints, not restart a full population by default.
Treat rate limits as dynamic scheduling inputs
Model each provider's actual limit dimensions: application, tenant account, user, route, resource cost, concurrency, and time window. RFC 9331 defines RateLimit and RateLimit-Policy fields, but providers may use other headers or semantics. Parse only documented signals, account for clock skew, and treat reset values as scheduling information rather than a promise of success. Combine token-bucket or leaky-bucket controls with observed response feedback and bounded exponential backoff with jitter.
On 429, reduce the matching budget rather than freezing unrelated providers or tenants. Respect Retry-After where defined, but cap delays according to product deadlines and surface growing staleness. On 401, distinguish expired access token from revoked authorization; on 403, distinguish missing scope, policy, and resource denial; on 5xx, use circuit breaking and retry limits. Never retry deterministic validation errors. Record provider request IDs and safe reason metadata for support.
| Response or condition | Likely class | Scheduler action | Tenant-facing state |
|---|---|---|---|
| 429 with reset signal | Quota exhausted | Delay matching budget with jitter | Delayed with updated freshness |
| 401 after refresh attempt | Authorization invalid | Pause connection | Reconnect required |
| 403 missing scope | Insufficient grant or policy | Stop affected operation | Permission action required |
| 400 schema rejection | Deterministic data or contract error | Quarantine record | Partial failure with reason |
| 5xx or timeout | Transient or unknown outcome | Query idempotency, then bounded retry | Degraded, no duplicate promise |
Make synchronization idempotent and versioned
Define whether each flow synchronizes state, appends events, or invokes a side effect. State upserts can use stable external IDs and compare versions. Event creation needs durable deduplication and provider idempotency support where available. Side effects such as sending messages or issuing refunds require stronger confirmation and compensation plans. Maintain mapping versions with source and destination schemas, null behavior, enums, precision, time zones, ownership, and deletion semantics. Quarantine incompatible records without advancing a cursor past unrecorded work.
For incremental reads, store the committed cursor only after the corresponding page and downstream writes are durably accounted for. Include overlap and deduplication when provider cursors or modification times can miss boundary updates. Webhooks should be authenticated, quickly persisted, deduplicated by event identity, and processed asynchronously. Assume delivery can be duplicated, delayed, or reordered. Reconcile periodically against provider state because webhooks are a latency mechanism, not complete proof.
Expose connection health and isolate recovery
Health should report authorization, last successful read and write, source and destination cutoffs, current lag, backlog, quota posture, mapping version, error categories, and required action. Avoid one green status based on a recent token call. Give tenants a safe reconnect, pause, test, and scope-review flow. Internally, measure per-tenant latency and failure without placing tenant identity in uncontrolled metric dimensions; use secure drill-down from bounded aggregate labels.
Connection deletion is a lifecycle operation, not a row delete. Stop new scheduling, drain or cancel queued work under declared rules, revoke provider grants when supported, remove webhooks, destroy secret material, expire staging data, and retain only the audit evidence required by policy. Clarify whether synchronized business records remain in either product. A tenant should see deletion progress and final state, while operators reconcile that no active token, callback, cursor, or scheduled job still references the retired connection.
Recovery acts on one connection and known work range. Preview replay counts and side-effect classes, require authorization, and preserve an audit trail. Reconcile intended operations with provider results before replaying unknown timeouts. Test revoked tokens, rotating refresh tokens, quota exhaustion, backfill competition, schema changes, duplicate webhooks, slow tenants, and provider outages. Verify other tenants remain within service objectives. This noisy-neighbor test is as important as a successful happy-path sync.
Key takeaways
- Model each external account connection as a tenant-scoped product object with explicit authority, mapping, checkpoint, health, and owner.
- Vault and audit credentials per connection, follow current OAuth security practice, and stop refresh races and revoked-token retry storms.
- Partition work and apply fair scheduling, bounded concurrency, backpressure, and poison-record isolation.
- Interpret each provider's quota dimensions and response semantics instead of using one global requests-per-second value.
- Use idempotent operations, durable cursors, webhook deduplication, reconciliation, and connection-bounded recovery.
Frequently asked questions
Should one provider token serve all tenants?
Only when the provider's legitimate authorization model explicitly grants a service account access to those tenants and isolation remains enforceable. Customer-controlled integrations usually need separate tenant or account authority so revocation, scope, and audit are independent.
How should shared application quotas be divided?
Reserve critical capacity, apply fair weighted budgets, bound each tenant's concurrency, and adjust from documented provider signals. Product tiers may influence priority, but one tenant should not consume the capacity required to keep others functional.
Do webhooks remove the need for reconciliation?
No. Webhooks improve freshness but can be delayed, duplicated, reordered, misconfigured, or missed. Persist and deduplicate them, then run periodic state reconciliation to detect gaps.
Conclusion
SaaS-to-SaaS connectors scale when tenancy governs every layer: credentials, configuration, queueing, quota, data, telemetry, and recovery. A shared connector platform can retain operating leverage while per-connection contracts contain failures and authority. The architecture then supports many customer integrations without making every external API incident a platform-wide event.