Skip to main content

Bridge user guide

Updated

Overview

Bridge is the integration and automation hub of The One Stack. It pulls data out of the tools you already use (PSAs, RMMs, documentation platforms, accounting systems, Microsoft 365), keeps that data in sync, and lets you wire together automated workflows without writing code. Bridge is also where your team (and your customers) get API keys to call the products published for API access (PSA, CRM, RMM and CMDB today) through a single gateway. Anything not published is refused.

Finance → Payment Sync (/psa/admin/integrations). Connect QuickBooks Online (or Xero) and run invoice/payment sync here. These connections are owned by Bridge. You can also reach this page from Settings → Integrations & Migration → Integrations (same URL). Note: Finance → Billing Integration (/psa/finance/billing/settings) holds PSA's own billing settings. It does not set up the QuickBooks sync, so don't label it "QuickBooks."

Key Features

  • Connections to 12 external platforms: ConnectWise Manage, Autotask, NinjaOne (Ninja RMM), Datto RMM, QuickBooks, Xero, Microsoft 365, Google Workspace, Pax8, Hudu, IT Glue, and Snipe-IT
  • One-time historical imports to pull years of data out of a legacy system into The One Stack
  • Recurring sync profiles on hourly, daily, weekly, or manual schedules
  • Integration Flows: a visual automation builder with triggers, actions, filters, branches, loops, delays, and error handlers
  • Transformer: 28 built-in operations for cleaning and reshaping data during an import (rename fields, split values, date formatting, lookup tables, deduplication, filtering, and more)
  • Inbound webhook receiver: accept events from any outside system at a URL you control, with HMAC, Basic auth, or token verification
  • Outbound webhook subscriptions that keep external systems notified of changes
  • Platform API keys (prefix bridge_) for your team and customer-scoped keys (prefix bridge_co_) for each of your clients
  • Gateway proxy that exposes the products published for API access (PSA, CRM, RMM and CMDB today) at one URL
  • Custom connectors for any HTTP API that isn't in the built-in catalog
  • Conflict detection and resolution when the same record gets edited in two places
  • Error recovery screen for retrying, skipping, resolving, or correcting failed records — each recurring failure pattern carries Bridge's own Suggested fix for that error category

How To: Connect an External Tool

  1. Open Bridge and go to Connections.
  2. Click New Connection and pick the platform (for example, NinjaOne).
  3. Enter the credentials the platform asks for. For NinjaOne, that's your API URL plus a Client ID and Client Secret. For ConnectWise Manage, it's Company ID, Public Key, Private Key, and Client ID. For OAuth platforms like Xero, Pax8, or Microsoft 365, you'll enter client credentials.
  4. Click Test Connection. Bridge encrypts and stores your credentials and tries a live call. If it fails, the error is shown right on the connection.
  5. Save the connection. Bridge sets the status to Active.

How To: Run a Historical Import

  1. Go to the connection you just created and click Import.
  2. Pick the entity types you want to bring over (companies, tickets, contacts, time entries, etc.).
  3. Choose a de-dup strategy: skip duplicates, update existing records, or allow duplicates.
  4. Review the field mapping. Bridge suggests defaults; change any you want and save the mapping as a template for next time.
  5. Click Preview to see a sample of how records will look after import.
  6. Click Start Import. You'll see live progress, and any failed rows land in Error Recovery where you can retry or skip them.

How To: Build a Sync Profile

  1. Go to Sync Profiles and click New Profile.
  2. Pick the connection and the entities to sync.
  3. Choose a direction (inbound, outbound, or bidirectional) and a frequency (realtime, hourly, daily, weekly, or manual).
  4. Save. The profile will run on schedule. You can also click Trigger to run it right now.
  5. Open the profile to see each run's counts: processed, created, updated, skipped, errored.

How To: Build an Integration Flow

  1. Go to Flows and click New Flow.
  2. Drag a Trigger node onto the canvas. Triggers can be a schedule, a webhook, or a bus event.
  3. Add Action, Transform, Filter, Delay, Branch, Loop, or Error Handler nodes and connect them with edges.
  4. Configure each node. For a Filter, pick a field, an operator (equals, contains, starts with, is empty, and about a dozen more), and a value.
  5. Click Validate. Bridge checks that every node is reachable from the trigger and tells you if anything is stranded.
  6. Click Activate. The flow will run every time its trigger fires. You can watch executions on the flow's Executions tab.
  7. If you'd rather not start from scratch, browse Flow Templates and click Install on one that fits.

How To: Use the Transformer

  1. Open a sync profile or import and go to Field Mappings.
  2. For each field, pick a transform: format a date, map status values from the external system to yours, truncate to a length, concatenate columns, split a column, apply a lookup table, uppercase/lowercase, trim, convert to number or boolean, or fall back to a default.
  3. Chain multiple operations into a pipeline: for example, trim a field, then apply a regex extract, then map to your internal status values.
  4. Save as a Transform Pipeline so you can reuse it across connections.

How To: Set Up an Inbound Webhook

  1. Go to Inbound Webhooks and click New.
  2. Name it and give it a slug (your URL will be https://api.theonestack.com/api/v1/bridge/hooks/in/your-slug).
  3. Pick a verification type: none, HMAC signature, Basic auth, or bearer token. Bridge generates the secret.
  4. Define the field mappings — which parts of the incoming payload map to which fields.
  5. Pick a routing type: publish a bus event, write to a connection, or call a product API.
  6. Save. Send the URL to whatever system you want hooked in. Every request is logged with payload, headers, source IP, and the routing result.

How To: Issue API Keys

  1. For a customer: go to Company API Keys, select the company, and pick which products the key can reach. These keys start with bridge_co_ and can be revoked any time.
  2. Both kinds are used with Authorization: Bearer <key>, X-Bridge-Key, or X-API-Key when calling the products published for API access (PSA, CRM, RMM and CMDB today) through the gateway. Anything not published is refused.

How To: Call the Gateway

Point at https://api.theonestack.com/v1/<product>/<path> with your key. For example, to list PSA companies: GET https://api.theonestack.com/v1/psa/companies with your Bearer key. The gateway enforces your scopes, plan tier, and rate limit, then forwards to the right product.

Frequently Asked Questions

How are credentials stored? Each org gets its own encryption key from Azure Key Vault. Credentials are encrypted with AES-256-GCM before they hit the database and are never returned to the UI.

How fast can a flow run? A flow starts whenever its trigger fires. Inline actions run immediately; delay nodes cap at 60 seconds so long waits don't hold up the worker — for hours or days of wait, use a scheduled trigger.

What happens if a sync fails mid-run? Failed records go to Error Recovery. You can retry them individually, skip them, mark them resolved, or correct the record data and save it as manually fixed. Each recurring failure pattern also carries a Suggested fix — Bridge's own guidance for that error category.

How are conflicts handled when the same record changes on both sides? Bridge detects conflicts and surfaces them on the Conflicts page. You can resolve each one manually (keep local, keep external, merge, or skip), or write auto-resolve rules by connection, entity, and field.

Can I version or preview flows before going live? Flows are saved as drafts until you click Activate. Duplicate a flow before changing it if you want a backup. Validation checks reachability before activation.

Do customer-facing API keys cost anything extra? No. You can issue as many bridge_co_* keys as you need. Each one gets its own scope and IP allowlist, and all usage shows up on the API Usage screen.

Troubleshooting

Connection test fails. Open the connection and look at the Last Error. Most failures are credential-related (expired token, wrong subdomain, missing permissions on the API role). Fix the credentials and Test again.

Sync runs but no records come over. Check the sync profile's entity types are actually selected, and confirm field mappings aren't filtering everything out. Field Mappings lets you preview a sample.

Flow execution failed. Go to the flow's Executions tab and click the failed run. Every node's input, output, and error is captured. If the flow has an Error Handler node, the failed node's output is routed there automatically.

Webhook returns 401. Your verification secret doesn't match. Regenerate the secret on the Inbound Webhook, update the sending system, and try again.

API call returns 403 with Upgrade required to access <product> via API gateway. The org's plan doesn't cover that product. Upgrade the org's plan or use a key on an org that has access.

API call returns 429. You've hit the daily API call limit for your org's plan. Check the X-RateLimit-Remaining header and wait for the Retry-After window before retrying.

Import stuck at "discovering". The external API is either slow or rate-limiting Bridge. Pause the import, give it a few minutes, and resume.