How to Build Post-Connection Configuration UIs for SaaS Integrations

You shipped OAuth. The token exchange works. You are sitting in the final review meeting for a six-figure enterprise contract. The prospect loves your core product. They finally clicked "Connect" on your new Salesforce integration. They are redirected back to your application, ready to sync their data.\n\nThen, they hit a brick wall.\n\nYour UI presents a blank text input asking for a "Salesforce Custom Object API Name" and a "Record Type ID." The user, a VP of Sales, has no idea what a Record Type ID is. They open a new tab to search for it, get distracted by a Slack message, and close the window.\n\nThat integration is now functionally dead. \n\nThis is the post-connection configuration problem, and it is where most B2B SaaS integrations bleed activation. Building high-converting setup UIs requires acknowledging a harsh reality: token exchange is only step one. The real engineering challenge is collecting the right metadata without forcing non-technical users to read API documentation.\n\nThis guide walks through the end-to-end architecture for building setup UIs that appear after authentication. It covers the data model, the dynamic form rendering layer, the API calls that populate dropdowns, and the edge cases (rate limits, pagination, re-auth) that break naive implementations.\n\n## The Integration Activation Gap: Why OAuth is Only Step One\n\nEngineering teams often treat authentication as the finish line. You successfully exchange an authorization code for an access token, store it securely, and mark the integration as "connected." But a stored token does not equal a working integration.\n\nBetween the OAuth callback and the first successful data sync sits a configuration step that answers questions the connected API cannot answer on its own:\n\n* Which of the user's five Slack workspaces should we sync?\n* Which HubSpot pipeline represents "closed-won" for this tenant?\n* Which custom fields on the Salesforce Contact object map to your internal lead_score?\n* Should we sync historical data or only new records going forward?\n\nGet this step wrong and the numbers get ugly fast. Across 62 B2B SaaS companies, the average user activation rate sits at just 37.5%, meaning nearly two-thirds of users abandon a product before experiencing its core value. Many of these drop-offs occur precisely at this moment—during complex, poorly designed setup flows.\n\nThe payoff for fixing it is real. Products with four or more active integrations deliver 18 to 22 percent higher retention rates once integrations are actually adopted. "Integration activation rate"—the share of connected accounts that reach a working, syncing state—deserves its own dashboard, separate from OAuth completion.\n\n:::callout{type="info"}\nDefinition: Post-connection configuration is the setup phase between a successful OAuth callback and the first successful data sync. It typically includes workspace selection, data scoping filters, field mapping, and sync schedule configuration.\n:::\n\n## Anatomy of a High-Converting SaaS Integration Setup Flow\n\nA well-designed post-connection flow collects the minimum viable configuration and defers everything else to sensible defaults. Simplifying setup forms directly increases conversion. UXCam's SaaS Onboarding Benchmark Study found that reducing a sign-up form from 7 fields to 3 fields cut overall funnel abandonment by 44.7%. Apply the same instinct here: progressive disclosure beats a single wall-of-fields screen.\n\nAs detailed in our guide to post-connection configuration UI patterns, a high-converting post-connection UI typically consists of four distinct phases:\n\n### 1. Workspace and Tenant Selection\nMany SaaS platforms (like Slack, Notion, Asana, Jira, or GitHub) expose multiple workspaces or organizations behind a single user identity. Your first screen must ask the user which workspace they intend to sync.\n\nDo not ask the user to type in a Workspace ID. Your backend should immediately query the provider's /users/me or /workspaces endpoint using the fresh access token, and your UI should render a clean, searchable dropdown containing human-readable workspace names.\n\n### 2. Data Scoping and Filtering\nEnterprise customers rarely want to sync their entire database. They want to filter the noise before it ever hits your database—syncing specific subsets of data like "Opportunities in the 'Closed Won' stage" or "Tickets tagged 'High Priority'."\n\nYour UI needs to dynamically fetch the available filters (e.g., pipeline stages, tags, record types) from the provider and present them as multi-select checkboxes. This requires your backend to normalize the concept of "tags" across different platforms so your frontend component can remain generic.\n\n### 3. Dynamic Field Mapping\nThis is the most complex component of the post-connection UI. If you are syncing contacts from a CRM into your application, your application has a fixed set of standard fields (First Name, Last Name, Email). The customer's CRM, however, has a highly customized schema (e.g., Custom_Lead_Score__c).\n\nThe UI must present a two-column mapping interface. The left column lists your application's required fields. The right column is a dropdown containing the provider's fields, fetched dynamically at runtime via their schema API. Hardcoded field lists are a guaranteed way to fail enterprise procurement.\n\n### 4. Sync Cadence and Direction\nFinally, the user must define how the integration behaves. Give users a small set of clear choices: "Sync every 15 minutes," "Sync historical data from the last 90 days," or "Real-time via webhook." Do not expose cron expressions. Exposing these options clearly prevents downstream support tickets about "delayed data."\n\nmermaid\nflowchart LR\n A [OAuth Callback] --> B [Fetch Workspaces]\n B --> C [User Picks Workspace]\n C --> D [Fetch Scoping Options]\n D --> E [User Picks Filters]\n E --> F [Fetch Custom Fields]\n F --> G [User Maps Fields]\n G --> H [Pick Sync Cadence]\n H --> I [Persist Config & Trigger First Sync]\n\n\n## Anti-Patterns: What Causes Post-Connection Drop-Off\n\nBefore architecting the ideal solution, we must identify the anti-patterns that destroy integration activation rates. These show up in almost every homegrown integration flow:\n\n* Asking for Raw API IDs: "Please paste your Salesforce Record Type ID" is a request to abandon. Non-technical users do not know how to inspect network requests or write SOQL queries. If you need it, fetch it via the API and render a dropdown.\n* Synchronous UI Blocking on Live Fetches: Fetching a list of 40,000 custom fields from an enterprise HubSpot instance can take seconds. If your frontend makes a synchronous request to your backend, which then synchronously calls the provider, the browser will hang. Users will assume it is broken and refresh. All external fetches must be asynchronous with clear loading states. Paginate server-side and use type-ahead search.\n* Silent Failures and Lack of Inline Validation: If a user maps a "String" field in your application to a "Boolean" field in the provider, or picks a Jira project lacking the required issue type, tell them before they hit "Save." Your schema-fetching logic must return data types, and your UI must disable incompatible mapping options.\n* Silent Scope Failures: If your OAuth scope did not include admin.workspace.read, the workspace dropdown will be empty. Detect this and offer a re-auth CTA—do not just render a blank select.\n* Losing State on Refresh: If a user reloads mid-setup, their partial configuration should persist. Store it server-side keyed by the connection ID.\n* One-Size-Fits-All Forms: Rendering the same 12 fields for Slack and Salesforce guarantees confusion. Setup UI must be provider-aware.\n\nFor a deeper catalog of these patterns, see our guide on Post-Connection Configuration UI Patterns for SaaS Integrations.\n\n## Building a Dynamic Post-Connection Configuration UI\n\nHere is the part most teams get wrong: they build a bespoke React component for every provider. Slack gets its own <SlackSetup />. Salesforce gets its own <SalesforceSetup />. By connector #15, the frontend is 40% of the integrations codebase, and every new provider takes a sprint to build.\n\nTo scale your integration ecosystem without writing custom code, you need a metadata-driven architecture. The industry standard approach is schema-driven rendering. Your backend generates a declarative JSON Schema describing the configuration steps based on the connected provider's API capabilities. A single generic form renderer on the frontend interprets this schema and renders the appropriate inputs.\n\nmermaid\nsequenceDiagram\n participant UI as Frontend UI\n participant Backend as Your Backend\n participant Unified as Unified API\n participant Provider as SaaS Provider\n \n UI->>Backend: Request Setup Schema (Provider ID)\n Backend->>Unified: Fetch Provider Config\n Unified->>Provider: GET /metadata/schema\n Provider-->>Unified: Raw Provider API Response\n Unified-->>Backend: Normalized JSON Schema\n Backend-->>UI: Render Dynamic Form\n UI->>Backend: Submit Configuration Payload\n Backend->>Unified: Save Connection State\n\n\n### The Schema Contract\n\nInstead of hardcoding a setup form, your backend responds with a JSON object defining the fields, their types, and dynamic options. A minimal schema for a setup step looks like this:\n\njson\n{\n "integration": "hubspot",\n "steps": [\n {\n "id": "select_pipeline",\n "title": "Choose a sales pipeline to sync",\n "fields": [\n {\n "key": "pipeline_id",\n "label": "Pipeline",\n "type": "remote_select",\n "source": {\n "unified_model": "crm.pipeline",\n "value_key": "id",\n "label_key": "name"\n },\n "required": true\n },\n {\n "key": "sync_stages",\n "label": "Which stages should we sync?",\n "type": "remote_multiselect",\n "source": {\n "unified_model": "crm.pipeline_stage",\n "depends_on": ["pipeline_id"],\n "value_key": "id",\n "label_key": "name"\n }\n }\n ]\n },\n {\n "id": "map_fields",\n "title": "Map custom fields",\n "fields": [\n {\n "key": "field_map",\n "type": "field_mapper",\n "source_schema": {\n "unified_model": "crm.contact",\n "discover": "custom_fields"\n },\n "target_schema": [\n { "key": "score", "label": "Lead score", "type": "number" },\n { "key": "segment", "label": "Segment", "type": "string" }\n ]\n }\n ]\n }\n ]\n}\n\n\nThree things make this work:\n1. remote_select fields declare an API source: The renderer knows how to call your backend, which proxies to the provider and returns a normalized list.\n2. depends_on handles cascading selects: When pipeline_id changes, stages refetch automatically.\n3. field_mapper uses runtime schema discovery: The tenant's custom fields are fetched live, not hardcoded.\n\n### The Rendering Layer\n\nOn the frontend, a single generic renderer (using a library like React JSON Schema Form) walks the schema:\n\ntypescript\nfunction SetupRenderer({ schema, connectionId }: Props) {\n const [values, setValues] = useState({});\n const [step, setStep] = useState(0);\n const current = schema.steps [step];\n\n return (\n <Form>\n <h2>{current.title}</h2>\n {current.fields.map((field) => (\n <FieldRenderer\n key={field.key}\n field={field}\n value={values [field.key]}\n dependencies={pickDeps(values, field)}\n connectionId={connectionId}\n onChange={(v) => setValues({ ...values, [field.key]: v })}\n />\n ))}\n <NextButton onClick={() => advance()} />\n </Form>\n );\n}\n\n\nFieldRenderer is a switch statement over field.type. When it encounters a remote_select, it triggers an asynchronous fetch to populate the dropdown. Add a new provider? You write a schema, not a component. Add a new field type? You extend the renderer once and every integration benefits.\n\nYou can explore exact implementation details in our guide on How to Build a Schema-Driven Post-Connection Configuration UI and Dynamic Post-Connection Configuration Architecture.\n\n### The Backend Contract\n\nThe backend needs to answer two kinds of requests from the renderer:\n1. GET /setup-schema/:integration - returns the JSON schema above.\n2. GET /setup-data/:connection_id/:source_key - fetches live data from the provider and normalizes the response.\n\nThe second endpoint is where a unified API layer earns its keep. Instead of writing per-provider fetchers, you make one normalized call:\n\ntypescript\n// The same code path for HubSpot, Salesforce, Pipedrive, Zoho...\nconst pipelines = await truto.unified.crm.pipelines.list({\n connection_id: connectionId,\n});\nreturn pipelines.data.map((p) => ({ value: p.id, label: p.name }));\n\n\n## Handling Edge Cases: Rate Limits, Pagination, and Re-Auth\n\nBuilding the happy path is straightforward. The real engineering complexity lies in handling the inevitable edge cases that occur when fetching live metadata during the setup flow. The enterprise tenant with 200,000 contacts will break a naive implementation.\n\n### Managing API Rate Limits During Setup\n\nWhen a user opens the field-mapper step, you may fire five parallel API calls to discover schemas. If you hit the provider's rate limit, the response comes back as an HTTP 429 (Too Many Requests). Your UI must not crash.\n\nTruto normalizes upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) regardless of what shape the underlying provider uses. Truto explicitly does not silently swallow the 429 or apply hidden backoff. It passes the error straight through to the caller.\n\nThis is a deliberate design choice: your setup UI knows better than any middleware whether to retry silently, show a "Give us a moment" toast, or defer the fetch. You must implement exponential backoff and circuit breakers:\n\ntypescript\nasync function fetchWithBackoff(url: string, attempt = 0): Promise<Response> {\n const res = await fetch(url);\n if (res.status !== 429) return res;\n\n const reset = Number(res.headers.get('ratelimit-reset') ?? 1);\n const wait = Math.min(reset * 1000, 2 ** attempt * 500);\n await new Promise((r) => setTimeout(r, wait));\n return fetchWithBackoff(url, attempt + 1);\n}\n\n\nWrap that in a max-attempts guard so a struggling provider does not turn into a hung setup screen.\n\n### Pagination for Large Datasets\n\nNever attempt to load all available options into a dropdown at once. A dropdown that fetches every custom field from a mature Salesforce org will time out. Two techniques solve this:\n\n* Server-side search: Expose a ?q= parameter and only return matches. The remote_select field type should debounce input and pass the query to your backend.\n* Cursor pagination: For genuinely large lists, use infinite scroll with cursor-based pagination rather than offset-based, which drifts as data changes. As the user scrolls to the bottom of the list, trigger an asynchronous fetch for the next page using the cursor returned by the unified API.\n\n### Handling Expired Tokens and Re-Authentication\n\nSometimes, a user authenticates an integration but leaves the setup tab open for 30 minutes before completing the configuration. By the time they click "Save," the access token may have expired. Scopes may also change if an admin adjusts permissions mid-setup.\n\nYour system must monitor token TTL (Time To Live). When a token expires, the platform should automatically use the refresh token to obtain a new access token in the background. However, if the refresh token is invalid or revoked, your UI must gracefully catch the 401 Unauthorized error, persist their in-progress config, kick them through a silent re-auth, and drop them back on the same step.\n\nmermaid\nsequenceDiagram\n participant UI as Setup UI\n participant API as Your Backend\n participant Truto as Unified API\n participant Provider as Upstream Provider\n\n UI->>API: GET /setup-data/custom_fields\n API->>Truto: unified.crm.customFields.list()\n Truto->>Provider: GET /schema\n Provider-->>Truto: 401 token expired\n Truto-->>API: 401 needs_reauth\n API-->>UI: {error: "reauth_required"}\n UI->>UI: Persist form state\n UI->>Provider: OAuth refresh flow\n Provider-->>UI: New tokens\n UI->>API: Retry GET /setup-data/custom_fields\n\n\n## Standardizing Setup Across 200+ APIs with Truto\n\nBuilding a dynamic, schema-driven UI and maintaining the normalized data models required to power it is a massive engineering undertaking. Every provider handles custom fields, pagination, and rate limits differently.\n\nThe schema-driven pattern only pays off if you can populate those remote_select and field_mapper fields without writing per-provider code. That is exactly what Truto's unified API layer and RapidForm are built for.\n\n* One Request Shape, Every Provider: unified.crm.pipelines.list, unified.ats.jobs.list—the same call signature works across HubSpot, Salesforce, Greenhouse, Workday, and 200+ others. Your setup UI's data-fetching code stops caring which provider it is talking to.\n* RapidForm: Renders dynamic setup flows from declarative JSON. You describe the fields, sources, and dependencies; RapidForm handles the frontend. Adding a new integration's setup UI is a config change, not a sprint.\n* Standardized Rate-Limit Headers: Upstream 429s surface as normalized IETF headers so your backoff logic is provider-agnostic.\n* Runtime Schema Discovery: Fetch a tenant's custom fields, pipelines, tags, projects, or workspaces on demand through a single normalized endpoint, feeding them directly into your field-mapper UI.\n\nA unified API abstracts away 80% of provider quirks, but you still own the product decisions—which fields to show, how much to auto-configure, and when to prompt for re-auth. Truto removes the plumbing so your product teams can focus on the flow.\n\n## Strategic Next Steps\n\nA production-grade post-connection configuration UI is one of the highest-leverage investments an integrations team can make. It sits directly on the activation curve, and every point of drop-off eliminated compounds into retention.\n\nA practical rollout sequence:\n\n1. Instrument first: Add analytics events for every step of your existing setup flow. Find the drop-off cliff before you rebuild.\n2. Pick your worst-performing connector: Rebuild its setup UI as a schema, not a hardcoded component. Measure the lift.\n3. Generalize the renderer: Extract the pattern into a reusable form engine backed by a centralized schema registry.\n4. Instrument continuously: Every new integration's schema ships with activation dashboards attached.\n\nBy moving to a metadata-driven architecture, you empower your product teams to ship new integrations rapidly, ensure a consistent user experience, and ultimately drive higher integration activation rates across your entire customer base.\n\n:::cta{buttonText="Talk to us" buttonUrl="https://cal.com/truto/partner-with-truto"}\nStop bleeding activation during integration setup. See how Truto's unified API and RapidForm can cut your post-connection setup UI from weeks per integration to hours. Book a technical walkthrough with our team.\n:::