Integration guides
Per-platform setup walkthroughs for the OAuth dev-portal steps an operator
has to do BEFORE OpenSteward can hand a Connect Link to their customers.
One guide per platform that uses auth_type: oauth2 or oauth2_cc.
Platforms on api_key / session / local don’t need a dev-portal app
and have nothing to put here.
A guide is only worth writing when it carries content the generic
/platforms/<vertical>/<platform> config page can’t: screenshots of the
dev portal, scope quirks, sandbox vs production hosts, subdomain handling,
partner-program gating, multi-auth paths, non-standard webhook signature
schemes. If none of that applies, don’t write one — the catalog will show
the platform as “no guide yet” and that’s the honest signal.
Getting synced data out
Section titled “Getting synced data out”Two guides here are not per-platform. They cover handing the records OpenSteward has synced to your own tools:
- Destinations — scheduled exports to Parquet on S3, GCS or Azure Blob, Iceberg-ready Parquet (experimental), or to Postgres, Snowflake, BigQuery and Databricks.
- Read-only SQL access — a read-only Postgres login for a BI tool or notebook, onto masked views (Postgres deployments only).
Choosing what to write
Section titled “Choosing what to write”Most adapters have no guide yet. The 80 existing guides (79 Semi-detailed + 1 Walkthrough-legacy) can be rewritten into Walkthrough v2 opportunistically. Every other adapter is fair game for authoring — start with the platforms your customers are connecting to most.
Structure
Section titled “Structure”docs/integrate/├── _template.md ← copy + fill in for new guides├── README.md ← you are here├── destinations.md ← exports to your lake or warehouse├── sql-access.md ← read-only SQL logins└── <vertical>/ ├── index.md ← vertical hub └── <platform>.md<vertical> is one of accounting / crm / customer-support /
docsign / ecommerce / inventory / logistics / payments /
projects; <platform> matches the adapter slug exactly (must appear
in docs/openapi/platform-slugs.json).
Writing a new guide
Section titled “Writing a new guide”- Copy
_template.mdto<vertical>/<platform>.md. - Replace the frontmatter placeholders. All required keys are listed
in the template —
check:guidesfails CI if any are missing. - Walk the dev portal end-to-end with a real account; take screenshots
along the way. Save under
docs/assets/screenshots/integrate/<vertical>/<platform>/. Name them with a numeric prefix (01-…,02-…) so directory listings sort correctly. - Run
pnpm check:guidesbefore opening the PR. - Update
last_verifiedwhenever you re-walk the guide — quarterly at most.
Formats
Section titled “Formats”Three formats validate; walkthrough-v2 is the canonical format for new guides:
- walkthrough-v2 (canonical):
## Walkthrough(numbered steps with screenshots) +## Platform-specific notes(bullets covering whatever differs from a generic OAuth flow). Optional## Webhooksand## Troubleshootingsections. See_template.md. - semi-detailed (existing format, 79 guides):
## Auth modelplus free-form sections. Don’t author new guides in this format; rewrite into walkthrough-v2 when you touch one. - walkthrough-legacy (existing format, 1 guide): a six-section
numbered template (
## 1. Prerequisites…## 6. Troubleshooting). Same — rewrite into walkthrough-v2 when convenient.
The Compact format (## Auth + ## Webhooks + ## Refused) is
not accepted — guides in that shape fail validation.
Maintainer-to-maintainer, plain-spoken. Active voice, sentence-case headings, address the reader as “you”. No “effortless / seamless / revolutionary” marketing language. Each section earns its keep — if there’s nothing platform-specific to say, omit the bullet rather than padding it.
Proper nouns stay cased: Shopify, QuickBooks, Xero, OAuth,
Postgres, GitHub. OpenSteward is always two words.
Validation
Section titled “Validation”pnpm check:guidesAsserts each guide:
- has all six required frontmatter keys —
vertical,platform,title,auth_type,estimated_time,last_verified(partner_programandwritten_byare optional) - declares a
verticalmatching the directory the file sits in - satisfies one of the three accepted format schemas above
- references a real adapter slug (cross-checked against
docs/openapi/platform-slugs.json) - has a
last_verifieddate that parses asYYYY-MM-DD(warns when > 180 days old — a warning, not a failure) - every screenshot path it embeds actually exists on disk
index.md hub pages are exempt from the frontmatter and heading checks.
check:guides chains into check:docs, so CI catches drift.
Coverage
Section titled “Coverage”/guides/integrate on the docs-server lists every OAuth adapter — plus
any non-OAuth adapter that has a guide anyway — with its status:
- ✅ Documented — fresh guide (< 180 days)
- ⚠️ Stale — guide exists but
last_verifiedis > 180 days old - ❌ Missing — no guide yet
- 🤝 Partner only — frontmatter
partner_program: true(operator needs to apply through the platform’s partner programme before any production credentials issue)
partner-only wins over stale: a partner-gated guide keeps that pill
however old its last_verified is.
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.