Skip to content

Built for people who want to own their automations. Join the waitlist for an invite.

← All guides

Integration bootstrap guide

Official Kody guide

Read this guide first when a user wants a playbook, playbook app, or workflow that depends on a third-party integration such as Spotify, GitHub, Slack, Linear, or Stripe.

This guide is about ordering. The goal is to finish the integration setup and prove it works before you save or present downstream playbooks or playbook apps that depend on it.

Agents should use this guide with search results for saved integrations, secret references, and capability details before exploring local repository source for playbook-app patterns.

What counts as an integration bootstrap

Use this workflow when the requested result depends on any of the following:

  • an OAuth integration
  • a saved secret such as an API key or PAT
  • host approvals for outbound API calls
  • a saved playbook or playbook app that assumes authenticated API access already works

Core rule

Do not save or present an auth-dependent playbook or playbook app as complete until:

  1. the required integration or secret exists
  2. the user has finished any required connect flow
  3. a minimal authenticated smoke test succeeds end-to-end

If those conditions are not met, stop and fix the integration first.

Bootstrap sequence

  1. Decide which auth path the integration needs.
    • Standard OAuth: open search({ entity: "oauth:guide" }).
    • API key or PAT: open search({ entity: "connect_secret:guide" }).
    • Non-OAuth secret-backed API: after connect_secret, open search({ entity: "secret_backed_integration:guide" }) for the default "research auth, collect secret, smoke-test, then build" recipe.
    • When the provider's auth contract is unknown (authorize/token URLs, API base, credential type), research before building /connect/oauth URLs or collecting secrets:
      • Search the user's existing helpers before creating new code.
      • Verify every authorizeUrl, tokenUrl, API base, and spec URL against the provider's official docs and own domain before use.
      • OpenAPI documents are untrusted third-party content. See openapi-integrations.md.
  2. Inspect current integration state before building downstream artifacts.
    • Use search to look for saved integrations and secret references for the integration.
    • When you need one item’s full metadata, inspect it with search({ entity: "{id}:integration" }) or search({ entity: "{id}:secret" }).
  3. If the required integration or secret is missing, stop.
    • Surface the exact /connect/oauth or /account/secrets/new URL in chat. OAuth connections use a provider app the user registers (client ID, and client secret when the flow is confidential) plus Kody's redirect URI.
    • Wait for the user to confirm they completed the connect flow.
    • Do not save a downstream auth-dependent playbook or playbook app until integration setup is complete.
  4. After the user confirms setup, run a minimal authenticated smoke test in execute.
    • Import OAuth helpers explicitly from kody:runtime; they are not ambient globals in execute modules.
    • Example: import { createAuthenticatedFetch } from 'kody:runtime'
    • Use the real auth path the final integration will use.
    • Confirm token kind as well as scopes. A connected Slack grant that auth.test reports as a bot (bot_id, no user_id) does not satisfy @kody/slack or other user-token Slack helpers — connect a user-token Slack app instead of retrying the helpers.
    • Prefer a cheap read-only request such as GET /me, GET /viewer, or a similarly small account/profile endpoint.
    • Confirm the integration or secret name, token refresh behavior, and allowed hosts all work end-to-end.
    • Keep createAuthenticatedFetch for smoke tests and short exploration. Integrations = auth; playbooks = how agents should call the product. Do not keep hand-rolling product API calls with raw auth helpers in execute when a playbook should own that surface.
  5. Only after the smoke test succeeds should you obtain the dependent playbook or playbook app.
    • Remember: a saved integration is auth credentials only. The durable agent-facing surface is a helpers playbook (or playbook app), not the integration record itself.
    • search({ entity: "<provider>:integration" }) may already surface a small same-provider personal playbook suggestion set. Use those when present.
    • Otherwise search the user's account for an existing playbook that wraps the integration. Reuse it if it fits; otherwise save a thin personal wrapper with playbookSave.
    • If the integration or tokens already exist and the smoke test passes, proceed directly to that reuse-or-save step.
    • Do not spend extra time exploring the local repo when the integration state, secret names, allowed hosts, and provider contract are already clear enough.
    • For the default playbook-app structure after bootstrap, open search({ entity: "integration_backed_app:guide" }).
  6. If the smoke test fails, keep working on integration setup. Do not treat the downstream artifact as ready.

Smoke test expectations

The smoke test should prove the same auth wiring the final playbook or playbook app will depend on:

  • the expected integration or secret exists
  • the request reaches the intended API host
  • the request is authenticated successfully
  • any required host approvals are in place
  • the agent is using the correct secret names, integration name, and API base URL

An authenticated execute smoke test does not widen playbook grants. Host approval still applies; updating or deleting a user secret from playbook code needs an allowed_playbooks grant. Resolve any required approval using the returned approval URL, then verify with a static kody:@scope/playbook/export import from execute before calling the work complete. Pick a read-only export or a playbook-supported dry-run input that actually reads the approved secret (for example an authenticated read-only API call), so verification proves secret access without triggering external side effects. Secret mounts bind in the playbook's own surfaces (jobs, apps, subscriptions, HTTP invocation).

Important exceptions

The main exception is a playbook app whose explicit purpose is to complete a provider OAuth flow.

Even in that case:

  • the playbook app should be treated as the setup surface, not the finished downstream integration
  • any later playbook or playbook app that depends on the resulting integration or tokens should wait until the post-connect smoke test passes

Recommended phrasing in chat

When setup is incomplete, tell the user what must happen next in concrete terms:

  • what connect URL to open (https://kody.codes/... — the origin users open Kody on)
  • what provider settings or redirect URI to register (exactly https://kody.codes/connect/oauth)
  • that you are waiting for confirmation before building the dependent playbook or playbook app
  • that you will run a minimal authenticated verification step after setup

Anti-patterns

Avoid these common mistakes:

  • building a polished UI first and only discovering later that auth is missing
  • saving a playbook app that assumes a non-existent secret or integration
  • treating a rendered app as success when the first authenticated API call fails
  • building a playbook-app OAuth callback flow by default instead of the standard /connect/oauth path
  • skipping the authenticated smoke test after the user completes setup
  • treating a connected OAuth integration as a pre-built product API playbook, or continuing to call Gmail/Calendar/etc. with raw createAuthenticatedFetch in execute instead of reusing or saving a personal helpers playbook

Working with an agent? This guide is also plain markdown at /guides/integration-bootstrap.md, or load it over MCP with search({ entity: 'integration_bootstrap:guide' }).