Runtime data flows
Four sequence diagrams covering the main runtime patterns: an API request through the cache, the sync worker job lifecycle, an OAuth connection, and an inbound webhook.
Chart 4a — API consumer GET → cache → upstream → response
Section titled “Chart 4a — API consumer GET → cache → upstream → response”A developer calls GET /v1/accounting/contacts/inv-1?connection_id=<uuid> directly on integration-server with a tenant-scoped Bearer key. The auth middleware resolves the key + scope + tenant; the per-vertical plugin attaches the data-store context; cachedGet decides cache-vs-live, fetches/transforms if needed, and writes back. Default mode is database (read-through cache).
Key points:
- No separate gateway service —
/v1/*lands directly onintegration-serverandunifiedAuthMiddlewareruns as apreHandler. A second per-verticalpreHandlerdecoratesrequest.cacheMode/.resourceStore/.verticalforcachedGet/cachedList/writeThrough/cachedDelete. ?is_live=trueis bypass-read, write-back — fresh upstream data is still written into the cache. A live bypass is visible to the caller too: every cached-route GET returnsX-OpenSteward-Cache: hit|miss|live|passthrough(absent on mutations), and hits addX-OpenSteward-Synced-Atwith the ISO time the rows were cached — thedata-store: live bypassINFO log remains for server-side auditing.dataStore.staleAfterSeconds(optional) treats rows older than the TTL as a miss;?is_liveis unaffected.- POST / PATCH / DELETE follow the same shape: live upstream first, then
writeThrough(orcachedDelete) into the cache. Errors after the upstream succeeds log at ERROR but don’t fail the response — the operator-visible recovery path is?is_live=trueor/admin/connections/:id/cache-clear. - Per-key rate limit is 600 req/60s (
DEFAULT_API_KEY_RATE_LIMIT); in-memory by default, shared across replicas viaREDIS_URL. A second, global per-IP bucket runs increateBaseServer— see services.md § Rate limiting for why requests presentingX-Admin-Secretskip it. - Token refresh is automatic when
isTokenExpired(creds)is true. It runs throughwithRefreshLock+refreshWithRotationGuard, which re-encrypts the credential, writes it back, and records the outcome on the connection row (last_refresh_at/last_refresh_status/last_refresh_error). A non-okoutcome returns 401TOKEN_REFRESH_FAILED. - The adapter transforms the platform’s raw response into the canonical Zod schema;
metadatapreserves the unmodified raw payload.
Chart 4d — SyncWorker job lifecycle
Section titled “Chart 4d — SyncWorker job lifecycle”Operators monitor + cancel jobs at /sync-jobs, and enqueue one from either connections view (POST /connections/:vertical/:id/sync in the admin UI, operator role) — that path goes through admin-api’s POST /api/sync-jobs and surfaces the upstream refusal verbatim, so a 409 SYNC_IN_PROGRESS reads as such rather than as a generic 500:

POST /v1/{vertical}/sync?connection_id=… enqueues a job, and so, without any client, does the SyncScheduler whenever a connection’s sync schedule says it is due (see services.md). One SyncWorker per vertical polls sync_jobs for pending rows at pollIntervalMs (default 1s). The worker walks the vertical’s LISTABLE_RESOURCES, paginates through each upstream resource, bulk-upserts into resources, and (in external mode) emits one resource.synced event per page or per row.
Key points:
/syncis a READ-scope endpoint. It is aPOSTbecause it enqueues a job, not because it changes anything upstream — the worker only lists upstream, and upserts and removes rows in the local cache. The route declaresconfig: { readSafe: true }, which is the one exemptionrequiresWriteScope()honours (and it must be exactlytrue); every other non-GET still needsvertical:write. This lets the recommended API-key preset, which omitsvertical:writeby design, refresh the data it can read.callback_urlstill requiresvertical:write, and the URL is validated at enqueue (validateCallbackUrl): https only, no embedded credentials, no loopback/private/link-local address.callback.tsre-resolves the name immediately before the POST, because a name can resolve elsewhere by the time the job runs. Supplying one makes the deployment issue an outbound request from inside the network, which is a different authority from “refresh my cache”.POST /synchas its own cap on top of the per-key bucket: 10 per hour per(vertical, apiKeyId), refused with 429SYNC_RATE_LIMITEDand aRetry-After.- Every
/syncroute — includingGET /sync/:id— needs?connection_id=; the auth middleware rejects a request without one with 400CONNECTION_ID_REQUIRED, and a job belonging to another connection reads back as 404 rather than leaking its id. - Other enqueuers, none with a client involved, each recorded as the job’s
origin: theSyncSchedulerevery 60 s (schedule— never-synced connections first, then the most overdue, at most two jobs waiting per vertical per replica), the OAuth callback of a Connect Link (connect; skipped for atrigger_onlylink, and a link completed through the credential form leaves the first sync to the scheduler), boot withDATA_STORE_AUTO_SYNC_ON_BOOT=true(boot; skipstrigger_onlyconnections), and the admin console’s Sync now (manual). Every one goes throughsyncStore.createIfIdle. - At a known end the worker removes cached rows the platform did not return (
sweepCollection), then marks the collection complete. A known end is a reportedhasMore, or a declaredmaxPageSizebehind a short page; a guessed end, or a sync that wrote no rows, removes nothing and drops the marker instead. Removal emits no event. So a key with onlyvertical:readcan, throughPOST /sync, remove cached rows other consumers of the connection were reading — never anything upstream. The limits, including rows removed that the platform still has, are in dev-api.md §7. createIfIdlerefuses a second active job for a connection — a partial unique index onsync_jobsenforces it, across replicas too — so a duplicate enqueue gets a 409 rather than racing two workers on the same connection.- One shared
CircuitBreakeracross all 9 verticals — a flapping upstream stops draining its job queue cleanly. pollIntervalMs+maxConcurrency+pageSizeare configurable viadataStore.syncPageSizeenv / config; sane defaults (1000ms / 2 / 500).- Worker shutdown:
SIGTERMcallsworker.stop()which clears the timer, aborts in-flightprocessJobcalls, waits up to 30s for them to drain, then resets any still-running rows back topendingso the next boot picks them up (resetRunning(vertical)). - Jobs older than 30 days are pruned daily by
dataStoreMaintenance(seeapps/integration-server/src/data-store-maintenance.ts).
Chart 4b — OAuth connection authorization
Section titled “Chart 4b — OAuth connection authorization”Two ways an OAuth dance starts: an admin/operator authorising from the wizard, or an end-customer opening a Connect Link. Both land on the same /auth/:vertical/:platform/connect → /auth/:vertical/:platform/callback pair; the callback branches on whether the pending state carried a sessionId.
Key points:
clientId,clientSecret,redirectUri,scopescome from the AdapterSettingsStore — operators set them via/setup/wizard/configureand they’re encrypted at rest.- The
redirectUrireplayed at exchange is the one the authorize URL carried — RFC 6749 §4.1.3 requires the token request to repeat it exactly. It comes from the adapter’s own configured Redirect URI, so it may sit on another origin than the deployment’s (an https-only provider on an http deployment — see local HTTPS). Only when the authorize URL carries noredirect_uriis it derived, in this order: explicitredirect_uriquery param (validated) →PUBLIC_BASE_URLenv →companyInfo.baseUrl→request.protocol+request.host(withtrustProxyhonouringX-Forwarded-*). Suffix is always/auth/{vertical}/{platform}/callback. The host carries its port — the code usesrequest.host, notrequest.hostname, which strips the port in Fastify 5 and would deriveredirect_urivalues on :80 for deployments served elsewhere. A tenant’s custom domain deliberately does not enter this order: OAuth callbacks stay on the canonical domain so a provider needs only one allowlisted URL. - The Connect Link URL handed to a customer uses
resolvePublicBaseUrlOrNull, which inserts the tenant domain after the env override and returnsnullrather than a base no customer’s browser could open. A single-label host (integration-server,admin-api) is the signature of a compose service alias: the session is still created, but the response carriesurl: nullandurlUnresolved: trueinstead of an unreachable address.docker-compose.ymldefaultsPUBLIC_BASE_URLtohttp://localhost:3010so links are addressable out of the box. - Scope requested at OAuth-start follows the link’s scope policy, resolved by
resolveOverrideScopesFor:read_onlysends the platform’s curatedreadScopes(falling back to the platform default when the platform has none),customsends the link’s own list,platform_defaultsends no override. It is a per-link policy, not a property of the connection. stateis a 256-bit random hex held single-use in an in-processpendingStatesmap;consumePendingStatedeletes it on first read. CSRF protection comes from unguessability + one-time consume, not HMAC.- Connect Link flows carry a
sessionIdin pending state; the callback marks theconnect_sessionconsumed, firesconnect_link.consumed, and 302s toredirectUrl(or the hosted thank-you page). Admin-tooling flows return a201JSON body and leaveowner_tenant_idNULL. - The credential write is encrypted with AES-256-GCM, key derived via scrypt from
STORE_SECRET+ the credential store’s salt (opensteward-v1). The salt is per-store, not per-vertical — every vertical’s connections share one table and one key. See persistence.md § Encryption for the full salt list.
Chart 4c — Inbound webhook → vertical → DLQ
Section titled “Chart 4c — Inbound webhook → vertical → DLQ”A provider sends a webhook to the webhook-gateway. The gateway verifies HMAC, persists the delivery, forwards to the vertical, and enqueues retry on failure.
Key points:
- Backoff schedule: 1s, 5s, 30s, 5m, 30m — 5 retries total before DLQ.
- The webhook-gateway always returns
200or202to the provider — never propagates a 5xx upstream, so providers never disable our endpoint for being “broken”. - Failed deliveries go to a
dlqstatus where they can be manually replayed viaPOST /webhooks/dlq/:id/retry. - HMAC secrets are configured per platform in
webhook-gateway/config/config.yml.
See also
Section titled “See also”- webhook-delivery.md — the full delivery state machine including DLQ replay
- auth-and-tenancy.md — what
tenantIdactually is and where it comes from - adapter-lifecycle.md — how the adapter’s
clientId/clientSecretgot into the AdapterSettingsStore in the first place
opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.