> ## Documentation Index
> Fetch the complete documentation index at: https://rollout.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# How Rollout Works

> Architecture, core concepts, data flow, and integration surface area.

This page explains Rollout's architecture and the building blocks you'll use throughout your integration.

## Architecture Overview

```mermaid theme={null}
flowchart LR
    subgraph YourApp["Your Application"]
        Backend["Backend Server"]
        Frontend["Frontend"]
    end

    subgraph Rollout["Rollout Platform"]
        Auth["Auth Service"]
        API["Universal API"]
        Webhooks["Webhook Service"]
        Sync["Sync to DB"]
    end

    subgraph Integrations["Connected Systems"]
        CRM["CRMs"]
        TMS["TMS"]
        LOS["LOS"]
        Email["Email"]
    end

    Backend -->|Step 1: Generate JWT| Auth
    Frontend -->|Step 2: Rollout Link| Auth
    Auth -->|Step 3: credentialId| Frontend
    Backend -->|Step 4: API calls| API
    API -->|Normalized requests| Integrations
    Integrations -->|Raw data| API
    API -->|Normalized responses| Backend
    Webhooks -->|Real-time events| Backend
    Sync -->|Continuous sync| YourApp
```

## Core Concepts

<AccordionGroup>
  <Accordion title="Client ID / Client Secret">
    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.**
  </Accordion>

  <Accordion title="authToken (JWT)">
    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.
  </Accordion>

  <Accordion title="Credential">
    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.
  </Accordion>

  <Accordion title="credentialId">
    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.
  </Accordion>

  <Accordion title="appKey">
    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.
  </Accordion>

  <Accordion title="Universal API">
    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.
  </Accordion>

  <Accordion title="Rollout Link">
    The embedded authentication UI component that handles OAuth flows, API key collection, and credential management. It's a drop-in React component (or vanilla JS script) that you add to your integrations page.
  </Accordion>
</AccordionGroup>

## Data Flow in Detail

<Steps>
  <Step title="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).

    ```javascript theme={null}
    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' }
    );
    ```
  </Step>

  <Step title="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.).

    ```jsx theme={null}
    <RolloutLink
      token={authToken}
      onSuccess={(credential) => {
        // Store credential.id in your database
        saveCredentialId(userId, credential.id);
      }}
    />
    ```
  </Step>

  <Step title="Store the Credential ID">
    When the user successfully connects, Rollout returns a `credentialId`. Store this in your database, associated with the user or tenant.

    ```sql theme={null}
    -- Example: add a column to your users table
    ALTER TABLE users ADD COLUMN crm_credential_id VARCHAR(255);
    ```
  </Step>

  <Step title="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.

    ```javascript theme={null}
    const response = await fetch('https://crm.universal.rollout.com/api/people', {
      headers: {
        'Authorization': `Bearer ${authToken}`,
        'X-Rollout-Credential-Id': credentialId
      }
    });
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Multi-System Behavior

<Warning>
  **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.
</Warning>

**Common questions:**

<AccordionGroup>
  <Accordion title="If I update a contact, will it sync to other CRMs?">
    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.
  </Accordion>

  <Accordion title="Can a user connect multiple CRMs?">
    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.
  </Accordion>

  <Accordion title="How do I sync data between multiple systems?">
    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.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Get your API key" href="/getting-started/getting-your-api-key" icon="key">
    Obtain Client ID and Client Secret
  </Card>

  <Card title="Embed Rollout Link" href="/getting-started/show-the-authentication-ui" icon="link">
    Add the auth UI to your app
  </Card>

  <Card title="Make API requests" href="/getting-started/making-api-requests" icon="paper-plane">
    Read and write data
  </Card>

  <Card title="Set up webhooks" href="/advanced-guides/how-to-use-webhooks" icon="plug">
    Receive real-time updates
  </Card>
</CardGroup>