Skip to main content
This page explains Rollout’s architecture and the building blocks you’ll use throughout your integration.

​
Architecture Overview

​
Core Concepts

Your Rollout credentials, obtained from our team. The Client ID identifies your application; the Client Secret is used to sign JWTs on your server. Never expose the Client Secret in frontend code.
A short-lived JSON Web Token (15-minute expiry recommended) that you generate server-side using HS512. It authenticates requests to Rollout and identifies the end user/tenant making the request. Pass it to Rollout Link and include it as a Bearer token in API calls.
A connected account created when a user authenticates through Rollout Link. For example, when a user connects their Follow Up Boss account, Rollout creates a credential that stores the OAuth tokens or API keys needed to access that account.
The unique identifier for a credential. You store this in your database (associated with the user/tenant) and pass it in the X-Rollout-Credential-Id header when making API calls. This tells Rollout which connected account to use.
The identifier for a specific connector (e.g., followupboss, lofty, skyslope). You can use this to filter which integrations appear in Rollout Link or to identify which system a credential is connected to.
Rollout’s normalized REST APIs. Instead of learning the quirks of each CRM/TMS/LOS API, you use a single, consistent interface. The same endpoint structure and data model works across all supported systems.

​
Data Flow in Detail

1

Generate an Auth Token

Your backend creates a JWT using your Client Secret. The JWT includes claims like sub (user/tenant ID) and exp (expiration time).
const jwt = require('jsonwebtoken');

const authToken = jwt.sign(
  { sub: userId, iat: Math.floor(Date.now() / 1000) },
  process.env.ROLLOUT_CLIENT_SECRET,
  { expiresIn: '15m', algorithm: 'HS512' }
);
2

User Connects via Rollout Link

Your frontend renders Rollout Link with the auth token. The user sees a list of available integrations, selects one, and completes the auth flow (OAuth, API key, etc.).
<RolloutLink
  token={authToken}
  onSuccess={(credential) => {
    // Store credential.id in your database
    saveCredentialId(userId, credential.id);
  }}
/>
3

Store the Credential ID

When the user successfully connects, Rollout returns a credentialId. Store this in your database, associated with the user or tenant.
-- Example: add a column to your users table
ALTER TABLE users ADD COLUMN crm_credential_id VARCHAR(255);
4

Make API Calls

Use the credential ID to read/write data through the Universal API. Include your auth token as a Bearer token and the credential ID in the header.
const response = await fetch('https://crm.universal.rollout.com/api/people', {
  headers: {
    'Authorization': `Bearer ${authToken}`,
    'X-Rollout-Credential-Id': credentialId
  }
});
5

React to Changes

Option A: Webhooks — Rollout sends HTTP POST requests to your endpoint when data changes in the connected system.Option B: Sync to DB — Rollout continuously syncs data to a Rollout-hosted Postgres database for your account. Query with standard SQL and build views/indexes on top.

​
Multi-System Behavior

Writes are scoped to a single credential. When you call the API with a credential ID, the write goes only to that specific connected system. Rollout does not automatically propagate changes to other CRMs.
Common questions:
No. Each API call targets the specific system tied to the credential ID you pass. If a user has connected multiple CRMs and you want to sync a contact to all of them, your app must make separate API calls for each credential.
Yes. Each connection creates a separate credential. Your app can store multiple credential IDs per user and decide which one(s) to use for each operation.
Use Sync to DB to get data from all connected systems into your Rollout-hosted Sync to DB Postgres instance, then implement your own orchestration logic to determine what to write back and where.

​
What’s Next?

Get your API key

Obtain Client ID and Client Secret

Embed Rollout Link

Add the auth UI to your app

Make API requests

Read and write data

Set up webhooks

Receive real-time updates