--- title: "End-to-End Tutorial: Building a White-Labeled Integration Marketplace for SaaS" slug: end-to-end-tutorial-building-a-white-labeled-integration-marketplace-for-saas date: 2026-08-23 author: Nachi Raman categories: [Engineering, Guides, By Example] excerpt: "A complete engineering tutorial on architecting a white-labeled integration marketplace for B2B SaaS, featuring runnable Link SDK code and database schemas." tldr: Building a native integration marketplace requires choosing between embedded iPaaS and unified APIs. Unified APIs offer superior scalability by eliminating integration-specific code via declarative schemas. canonical: https://truto.one/blog/end-to-end-tutorial-building-a-white-labeled-integration-marketplace-for-saas/ --- # End-to-End Tutorial: Building a White-Labeled Integration Marketplace for SaaS Your enterprise prospect just asked for native integrations with HubSpot, Salesforce, Workday, and NetSuite. Your CTO estimates six months of engineering time. Sales says the deal closes in five weeks. Every quarter, this exact conversation drains your pipeline and burns your senior engineers on OAuth flows they will be forced to maintain forever. If you are evaluating [how to build a white-labeled integration marketplace](https://truto.one/how-to-build-a-white-labeled-integration-marketplace-for-your-saas/) for your B2B SaaS application, the architectural decision you make today will dictate your engineering velocity for the next three years. You can either hardcode individual OAuth flows, embed a clunky visual workflow builder, or utilize a unified API to programmatically handle data normalization. This guide provides a deep, technical blueprint for architecting a native integration marketplace. We will break down the database schema required to avoid integration-specific code, examine the trade-offs between embedded iPaaS and unified APIs, provide runnable code for embedding a Link SDK into your frontend, and handle messy production realities like token refresh, webhook verification, and rate limits. This is written for engineering leads and product managers who have already burned a quarter on a single custom connector and want a scalable way out. ## Why Your SaaS Needs a White-Labeled Integration Marketplace Missing integrations kill deals. Everything else is commentary. **A white-labeled integration marketplace is a native, in-app portal where your customers can browse, authenticate, and manage third-party software connections without leaving your host application.** Instead of building bespoke settings pages for every provider, a marketplace centralizes configuration, credential vaulting, and error handling into a single, cohesive user interface. Integrations are no longer a roadmap item—they are a hard revenue gate. According to Gartner's 2024 Global Software Buying Trends report, the ability to integrate into other systems is the number one sales-related factor driving a software decision. In the 2023 edition, integrations ranked as the third overall factor behind trust and sales flexibility. Furthermore, InboxInsight's 2024 B2B Tech Buyer Behavior report found that 90% of B2B buyers agree a vendor's ability to integrate with their existing technology stack significantly influences their decision to add them to a shortlist. When enterprise procurement teams request native connections, they expect those connections to live directly inside your application. Sending users to a third-party automation tool or forcing them to copy-paste API keys into a generic Notion document signals that your product is not enterprise-ready. A native, white-labeled marketplace fixes three specific problems: - **Perceived surface area.** A catalog of 40 well-known logos looks like a mature platform. Three integrations hidden behind a "Contact Sales" button does not. - **Self-service activation.** Customers connect their own accounts, cutting your Customer Success team out of a 90-minute onboarding call per integration. - **Compliance defensibility.** OAuth-scoped, per-tenant credential storage passes SOC 2 and vendor security reviews. Sharing raw API keys does not. If you want a deeper breakdown of the components that make up these portals, see our [2026 architecture guide on integration marketplaces](https://truto.one/what-is-an-integration-marketplace-2026-architecture-guide/). ## Architectural Approaches: Build vs. Embedded iPaaS vs. Unified APIs When product managers commit to shipping an integration marketplace, engineering teams typically [evaluate three paths](https://truto.one/the-2026-unified-api-buyers-guide-architecture-costs-and-compliance/). Each has severe downstream consequences for technical debt and maintenance. ### Option 1: Building Custom Connectors from Scratch Building in-house means your backend team writes and maintains the OAuth handshake, token refresh logic, pagination handling, and data normalization for every single provider. You write a Salesforce OAuth handler, a HubSpot OAuth handler, a Workday SOAP client, a NetSuite TBA implementation, and a webhook receiver for each. The honest math: a single production-grade connector takes a mid-level engineer 6 to 12 weeks end-to-end. That estimate rarely includes the ongoing maintenance burden. Provider APIs change, rate limits vary wildly, and webhooks fail silently. You will spend roughly 20% of that engineer's time forever just to keep the existing connector alive. When you scale past five integrations, you are forced to dedicate an entire engineering pod to integrations. Fifty connectors is an entire department. This is an unscalable model for early-to-mid-stage SaaS companies. ### Option 2: Embedded iPaaS Embedded integration platform as a service (iPaaS) providers—such as Prismatic, Cyclr, or Workato Embedded—attempt to solve this by providing visual workflow builders that you can embed into your app via iframes. The pitch is real: you get faster time-to-market and a low-code interface for CS or solutions engineers to build recipes. However, they introduce a massive architectural compromise: your integration logic now lives in a third-party drag-and-drop builder, completely disconnected from your core codebase. iPaaS is workflow-first, not data-first. If your product needs to read a normalized list of employees or update a CRM contact, you are still writing custom per-provider logic inside the workflow builder. The visual canvas becomes technical debt with a nicer UI, forcing your users to interact with complex visual mapping tools for standard data syncs. For a deeper breakdown of this category, see our guide on [what is an embedded iPaaS](https://truto.one/what-is-an-embedded-ipaas-the-2026-architecture-guide-for-b2b-saas/). ### Option 3: Unified APIs Unified APIs approach the problem at the data layer. Instead of building visual workflows, a unified API normalizes the data models across hundreds of SaaS platforms into a single, predictable REST interface. One `GET /crm/contacts` call returns the exact same JSON shape whether the underlying provider is Salesforce, HubSpot, or Pipedrive. The architectural win is that integration logic becomes declarative configuration, not code. Adding a new provider means writing a mapping file, not shipping a new microservice. This allows your engineering team to build a native integration marketplace entirely in code, rendering the UI exactly how you want it, while offloading the integration-specific backend logic. Done well, this scales to 100+ connectors with the same team that shipped the first three. | Approach | Time to First Connector | Time to 50 Connectors | Ongoing Maintenance | |----------|------------------------|----------------------|---------------------| | Build in-house | 6-12 weeks | 3-5 years | 20% of eng capacity | | Embedded iPaaS | 2-4 weeks | 12-18 months | Medium (workflow drift) | | Unified API | Days | Weeks | Low (config-driven) | ## Designing the Database Schema for a Provider-Agnostic Marketplace The hardest part of a scalable marketplace is not the frontend UI. It is the backend data model. To build a highly scalable integration marketplace, you must eliminate integration-specific code from your database and runtime logic. The moment you write `if (provider === 'salesforce')` or create a database table named `hubspot_oauth_tokens`, your architecture is already brittle and will multiply across every service you own within 18 months. Here is the schema pattern that keeps things generic. Six core tables, zero provider-specific columns. ```mermaid erDiagram TENANT ||--o{ INTEGRATED_ACCOUNT : owns INTEGRATION ||--o{ INTEGRATED_ACCOUNT : instantiated_as INTEGRATION ||--o{ AUTH_CONFIG : defines INTEGRATION ||--o{ UNIFIED_MODEL_MAPPING : exposes INTEGRATED_ACCOUNT ||--o{ CREDENTIAL : stores UNIFIED_MODEL_MAPPING }o--|| UNIFIED_MODEL : maps_to INTEGRATION { uuid id PK string slug jsonb base_config string category } INTEGRATED_ACCOUNT { uuid id PK uuid tenant_id FK uuid integration_id FK jsonb config_override string status } CREDENTIAL { uuid id PK uuid integrated_account_id FK text encrypted_access_token text encrypted_refresh_token timestamp expires_at } UNIFIED_MODEL_MAPPING { uuid id PK uuid integration_id FK string unified_field string provider_path jsonb transform } ``` The key insight: `INTEGRATION` and `UNIFIED_MODEL_MAPPING` are configuration, not code. Adding Pipedrive support simply means inserting rows, not deploying a service. ### The Generic Execution Pipeline When a user connects a third-party account, your system stores a tenant-specific credential. When your application needs data, it calls a unified endpoint. Your system should rely on a generic execution pipeline that dynamically loads the provider's definition, injects the credentials, formats the request, and normalizes the response. ```mermaid sequenceDiagram participant ClientApp as Client App participant UnifiedAPI as Unified API Layer participant ConfigDB as Config Database participant UpstreamAPI as Upstream API (Provider) ClientApp->>UnifiedAPI: GET /crm/contacts UnifiedAPI->>ConfigDB: Fetch provider mapping & credentials ConfigDB-->>UnifiedAPI: Return declarative JSON model UnifiedAPI->>UnifiedAPI: Transform request using model UnifiedAPI->>UpstreamAPI: GET /services/data/v55.0/query UpstreamAPI-->>UnifiedAPI: Raw Provider JSON UnifiedAPI->>UnifiedAPI: Apply reverse mapping UnifiedAPI-->>ClientApp: Normalized JSON array ``` ### Config Override Hierarchy In a production system, standard mappings are rarely enough. Enterprise customers often use custom fields or custom OAuth apps because their security team refuses your default one. Your database schema must support a configuration override hierarchy: 1. **Provider defaults** (baked into the integration definition) 2. **Workspace overrides** (your tenant's global config) 3. **Integrated account overrides** (specific to one customer connection) Resolve them in that order at request time. Store overrides as JSONB so you can add fields without migrations. This allows a specific customer to map their custom `Employee_ID__c` field to your unified model without affecting other tenants. ### Declarative Unified Models A unified model is a JSON document describing how to read from and write to every underlying provider. Instead of writing custom code to map a Salesforce `LastName` to your system's `last_name`, you define a mapping configuration. ```json { "unified_model": "crm.contact", "providers": { "salesforce": { "resource": "Contact", "fields": { "first_name": "FirstName", "last_name": "LastName", "email": "Email", "created_at": { "path": "CreatedDate", "transform": "iso8601" } } }, "hubspot": { "resource": "contacts", "fields": { "first_name": "properties.firstname", "last_name": "properties.lastname", "email": "properties.email", "created_at": { "path": "createdAt", "transform": "iso8601" } } } } } ``` The execution pipeline reads this at runtime. The same code path executes for every provider. By storing these definitions as declarative rules rather than executable code, you can add support for a new HRIS or CRM simply by writing a new JSON file. > [!TIP] > If you find yourself writing a switch statement on `provider_slug` anywhere in your hot path, stop. That logic belongs in the mapping config, not the runtime. ## Tutorial: Building the Marketplace UI and Link SDK Integration Developers evaluate APIs based on Time to First Call (TTFC)—the elapsed time from signing up to executing a successful, authenticated API request. To minimize friction, do not ask users to generate API keys or configure OAuth redirect URIs manually. Do not build a bespoke settings page per provider. Instead, embed a **Link SDK**. A Link SDK is a drop-in JavaScript component that renders the catalog, handles the authentication UI, manages the OAuth redirect, and handles the credential handshake natively inside your application. Our [full Link SDK guide](https://truto.one/how-to-build-and-document-a-high-converting-link-sdk-for-saas-integrations/) covers the design principles in depth. ### Step 1: Generate a Short-Lived Link Token on Your Backend Never expose long-lived API keys to the browser. Before launching the marketplace UI, your backend must generate a short-lived, scoped session token. This token securely identifies your tenant and authorizes the SDK to vault credentials on their behalf. ```javascript // Backend: Node.js / Express import { UnifiedClient } from '@unified-api/node'; const unifiedApi = new UnifiedClient({ apiKey: process.env.UNIFIED_API_KEY }); app.post('/api/integrations/link-token', requireAuth, async (req, res) => { const tenantId = req.user.tenant_id; // Call the unified API to generate a session for this specific tenant const { link_token } = await unifiedApi.linkTokens.create({ tenant_id: tenantId, allowed_categories: ['crm', 'hris'], ttl_seconds: 300 // 5-minute expiry }); res.json({ linkToken: link_token }); }); ``` ### Step 2: Render the Marketplace Catalog Render the catalog dynamically from your integrations table in your frontend. When the user clicks "Connect Salesforce", the SDK opens a secure modal, handles the OAuth handshake, securely vaults the refresh token, and returns a success callback. Notice what is missing: any code specific to Salesforce, HubSpot, or Pipedrive. ```jsx // Frontend: React import { useEffect, useState } from 'react'; import { openLinkSDK } from '@unified-api/link-react'; export default function Marketplace() { const [integrations, setIntegrations] = useState([]); const [connected, setConnected] = useState(new Set()); useEffect(() => { // Fetch available integrations from your generic database schema fetch('/api/integrations/catalog') .then(r => r.json()) .then(data => { setIntegrations(data.available); setConnected(new Set(data.connected.map(c => c.integration_slug))); }); }, []); const handleConnect = async (slug) => { // Fetch the short-lived token from your backend const { linkToken } = await fetch('/api/integrations/link-token', { method: 'POST' }).then(r => r.json()); openLinkSDK({ token: linkToken, integration: slug, onSuccess: (connection) => { console.log('Successfully connected:', connection.provider); setConnected(prev => new Set(prev).add(slug)); // Trigger an initial data sync job in your backend fetch(`/api/integrations/${connection.id}/sync`, { method: 'POST' }); }, onError: (err) => { console.error('Connection failed:', err.message); } }); }; return (

Integration Marketplace

Connect your existing tools to sync data automatically.

{integrations.map(integration => ( handleConnect(integration.slug)} /> ))}
); } ``` ### Step 3: Query Normalized Data Once connected, your product queries the unified API. The response shape is identical whether the backend is Salesforce, HubSpot, or a legacy Zoho CRM instance. ```javascript // GET /api/customers/:id/crm-contacts app.get('/api/customers/:id/crm-contacts', requireAuth, async (req, res) => { const account = await getIntegratedAccount(req.params.id); const contacts = await unifiedApi.crm.contacts.list({ integrated_account_id: account.id, limit: 100, updated_after: req.query.since }); res.json(contacts); }); ``` ### Sequence Diagram: The Full Connect Flow ```mermaid sequenceDiagram participant User participant App as Your SaaS App participant Backend as Your Backend participant Unified as Unified API participant Provider as "Provider (Salesforce)" User->>App: Clicks "Connect Salesforce" App->>Backend: POST /link-token Backend->>Unified: Create scoped link token Unified-->>Backend: link_token (TTL 5 min) Backend-->>App: link_token App->>Unified: openLink(token, 'salesforce') Unified->>Provider: OAuth authorize Provider->>User: Consent screen User->>Provider: Approves Provider->>Unified: Auth code callback Unified->>Provider: Exchange for tokens Provider-->>Unified: access + refresh tokens Unified-->>App: onSuccess(integrated_account_id) App->>Backend: Trigger initial sync Backend->>Unified: GET /crm/contacts Unified->>Provider: Provider-specific query Provider-->>Unified: Raw data Unified-->>Backend: Normalized data ``` ## Handling Rate Limits and Webhooks in Production Connecting an account is only the first hurdle. Operating integrations at scale requires a resilient approach to upstream failures. This is where most build-your-own marketplaces quietly fall apart six months post-launch. Both problems need explicit design. ### Normalizing Upstream Rate Limits One of the most dangerous assumptions engineering teams make is that a unified API will magically absorb rate limit errors. It will not. Every upstream API has different rate limits. Salesforce uses a complex concurrent request limit and daily API calls per org. HubSpot has burst and daily limits. BambooHR restricts calls based on a rolling window. Trying to abstract all of them behind one "smart" retry layer is a trap—you either retry when the caller wanted to fail fast, or you fail fast when the caller wanted to retry. Attempting to hide HTTP 429s (Too Many Requests) behind an opaque retry mechanism inevitably leads to distributed deadlocks and exhausted connection pools. The correct pattern is to surface the upstream signal cleanly and let the caller decide. A well-architected unified API passes the HTTP 429 error directly to your caller, normalizing the provider's disparate rate limit headers into standardized IETF headers: - `ratelimit-limit`: The maximum number of requests permitted in the current window. - `ratelimit-remaining`: The number of requests remaining in the current window. - `ratelimit-reset`: The time (in seconds) at which the rate limit window resets. Your application code is responsible for reading the `ratelimit-reset` header and backing off. Your retry logic then becomes predictable and works across every provider: ```javascript async function callWithBackoff(fn, maxRetries = 5) { for (let attempt = 0; attempt < maxRetries; attempt++) { try { return await fn(); } catch (err) { if (err.status !== 429) throw err; // Read the normalized IETF header provided by the unified API const resetSec = parseInt(err.headers['ratelimit-reset'] || '5', 10); const jitter = Math.random() * 1000; // Sleep until the window resets, plus jitter to avoid thundering herds await new Promise(r => setTimeout(r, resetSec * 1000 + jitter)); } } throw new Error('Rate limit retries exhausted'); } ``` ### Verifying Webhook Signatures Polling APIs for changes is inefficient and expensive. Production integrations rely on webhooks to receive real-time updates when a record changes. However, exposing a public endpoint to receive webhooks introduces a massive security vulnerability if you do not verify the payload. Every provider signs webhooks differently. Salesforce uses HMAC-SHA256 with a specific canonical string. HubSpot uses v3 signatures including the request method and URL. Stripe uses timestamped signatures to prevent replay attacks. When building your marketplace, your unified API layer should handle the initial ingestion of provider webhooks, verify the provider-specific signatures using stored secrets, and then forward a normalized event to your system with its own consistent signature. When your system receives this normalized webhook, you must verify it originated from your unified API provider using a timing-safe comparison to prevent attackers from guessing your secret by measuring response times. ```javascript import crypto from 'crypto'; import express from 'express'; const app = express(); function verifyHmac(payload, signature, secret) { const hash = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); // Use timingSafeEqual to prevent timing attacks return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(hash) ); } // Use express.raw() to preserve the exact payload bytes for HMAC verification app.post('/webhooks/unified', express.raw({ type: 'application/json' }), (req, res) => { const signature = req.headers['x-unified-signature']; const isValid = verifyHmac(req.body, signature, process.env.WEBHOOK_SECRET); if (!isValid) { return res.status(401).send('Invalid signature'); } const event = JSON.parse(req.body); // event.type is always normalized: 'crm.contact.created', 'hris.employee.updated' console.log('Received normalized event:', event.type); // Route the event to your internal business logic handleEvent(event); res.status(200).end(); }); ``` > [!WARNING] > Always verify signatures against the **raw body**, not the parsed JSON. Standard Node.js body parsers reorder keys and normalize whitespace, which instantly breaks HMAC comparisons. Always use `express.raw()` on webhook ingestion routes. ## Scaling to 100+ Integrations with Zero Custom Code Building a white-labeled integration marketplace is a strategic investment in your product's enterprise readiness. If you attempt to build custom connectors for every CRM, HRIS, and accounting platform, you will drown in technical debt, token refresh failures, and undocumented API edge cases. The entire point of the architecture outlined above is that the marginal cost of connector #47 is exactly the same as connector #4. When integration logic lives in declarative configuration—auth definitions, field mappings, and endpoint templates—onboarding a new provider becomes a pull request reviewed by one engineer in an afternoon, not a six-week sprint. The engineering teams that successfully scale to hundreds of connectors do three things well: 1. **They resist the temptation to write provider-specific code.** Every `if (provider === X)` is a future production incident. 2. **They treat unified models as product artifacts.** The `crm.contact` schema is versioned, peer-reviewed, and documented like any other public API contract. 3. **They buy the boring plumbing.** OAuth token refresh, credential encryption, webhook signature verification, and pagination normalization are not competitive differentiators. Own the integration logic that touches your customer's data; buy the plumbing. By leveraging a declarative unified API architecture and an embeddable Link SDK, you can deploy a native-feeling marketplace that scales infinitely. The result is a frictionless experience for your users, a massive reduction in engineering maintenance, and a product that breezes through enterprise procurement evaluations. > Stop burning engineering cycles on custom API integrations. Partner with Truto to embed a highly scalable, white-labeled integration marketplace into your SaaS product today. > > [Talk to us](https://cal.com/truto/partner-with-truto)