Build Integrations

Some of the most valuable apps connect an existing SOIS app to an outside service. A common example: sync invoices from the SOIS accounting app to QuickBooks. This guide explains how an integration app reads SOIS data safely and connects to an external service.

Integration apps are a first class category. They read another app's data through a governed contract, never its database directly, and only with the tenant's consent.

Two sides of an integration

An integration app talks to two things:

  1. A SOIS app (for example accounting, warehouse or contacts). You read or write its data through its published contract.
  2. An external service (for example QuickBooks). You call it with the tenant's own credentials.

Declare what you integrate with

Your project declares the SOIS apps it depends on. That declaration does two things: it tells SOIS which contracts your app may use, and it lets the tenant see and approve the access when they install your app.

Read SOIS data through the contract

Your app does not touch another app's tables. It reads through that app's contract, a stable set of operations and data shapes. Your agent builds your mapping against those shapes. During development you work against representative sample data, so you can build and preview the whole flow without a live connection.

At runtime, access is governed:

  • The tenant approves the cross app access when they install your app. This is part of your app's requested scopes.
  • The contract enforces what your app may read or write. Tenant isolation is never weakened.

Connect the external service

External credentials belong to the tenant, not to you. Your app declares the credentials it needs (for example an OAuth connection), and each installing tenant supplies their own. You never hold another tenant's credentials.

Example: sync invoices to QuickBooks

  1. Declare that your app integrates with the accounting app.
  2. Ask your agent to read the accounting invoice shape and build a mapping from a SOIS invoice to a QuickBooks invoice. Build and preview against sample invoices.
  3. Declare the QuickBooks OAuth credentials your app needs.
  4. When a tenant installs your app, they approve accounting access and connect their own QuickBooks account.
  5. At runtime, your app reads invoices through the accounting contract and pushes them to QuickBooks with the tenant's credentials, typically on a schedule or trigger.

Good practice

  • Map fields explicitly and handle the cases where an outside service expects data your source does not have.
  • Fail softly. If the external service is unavailable, retry rather than losing data.
  • Request only the scopes you need. Tenants approve narrow access faster and trust it more.

Next steps