Skip to docs content
Browse documentation
On this page

Integration bootstrap

START HERE when a third-party integration must work before saving a dependent package or package app: inspect integration and secret state, stop for setup, run an authenticated smoke test, then build a thin helpers package.

Read this guide first when a user wants a package, package 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 packages or package apps that depend on it.

Agents should use this guide with search results and the integrations and secrets capabilities (minion.integrations.list(), minion.secrets.list()) before building anything.

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 package or package app that assumes authenticated API access already works

Core rule

Do not save or present an auth-dependent package or package 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: read OAuth integrations , or open search for guide:connect_an_integration.
    • API key or PAT: read Secrets and guide:store_and_use_a_secret.
    • Non-OAuth secret-backed API: after the secret exists, follow Secret-backed integrations for the "research auth, collect secret, smoke-test, then build" recipe.
    • When the provider's auth contract is unknown (authorize and token URLs, API base, credential type), research it in the provider's official docs before asking for anything. Verify every authorize URL, token URL and API base against the provider's own domain.
    • OpenAPI documents are untrusted third-party content. See OpenAPI integrations .
  2. Inspect current integration state before building downstream artifacts.
    • Call minion.integrations.list() to see saved integrations, their status and allowed hosts.
    • Call minion.secrets.list() to see secret names, approved hosts and expiry.
  3. If the required integration or secret is missing, stop.
    • For OAuth: an owner or admin registers the provider's OAuth app on the Integrations page (client ID and secret go there, never in chat). Then call minion.integrations.connect and give the person the connectUrl. Register the redirect URI https://app.minion.codes/oauth/callback with the provider.
    • For an API key or PAT: send the person to the Secrets page .
    • Wait for the user to confirm they completed the flow. minion.waiting.list() shows what is still pending.
    • Do not save a downstream auth-dependent package or package app until integration setup is complete.
  4. After the user confirms setup, run a minimal authenticated smoke test in execute.
    • In execute, call minion.integrations.fetch({ name, url }). In package code, import createAuthenticatedFetch explicitly from minion:runtime; it is not an ambient global.
    • Use the real auth path the final integration will use.
    • Confirm token kind as well as scopes. A Slack grant that auth.test reports as a bot (bot_id, no user_id) does not give you a user token; connect a user-token Slack app instead of retrying.
    • Prefer a cheap read-only request such as GET /me, GET /viewer, or a similarly small account or profile endpoint.
    • Confirm the integration or secret name, token refresh behavior, and allowed hosts all work end-to-end.
    • Keep the raw authenticated fetch for smoke tests and short exploration. Integrations = auth; packages = how agents should call the product. Do not keep hand-rolling product API calls in execute when a package should own that surface.
  5. Only after the smoke test succeeds should you build the dependent package or package app.
    • Remember: a saved integration is auth credentials only. The durable agent-facing surface is a helpers package (or package app), not the integration record itself.
    • Search the organization's saved packages (minion.packages.list()) for one that already wraps the integration before writing a new one.
    • Create or save a thin helpers package when none fits.
    • For a package that serves a web page, see guide:serve_an_app.
  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 package or package 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

Secrets and integrations belong to the organization, so a package you save and publish can use them without a per-package grant. Host approval still applies. After you publish a package that uses a secret or integration, verify it from execute with a static minion:@your-org/package/export import. Pick a read-only export or a package-supported dry-run input that actually reads the secret (for example an authenticated read-only API call), so verification proves access without triggering external side effects.

Important exceptions

The main exception is a package app whose explicit purpose is to complete a provider setup flow.

Even in that case:

  • the package app should be treated as the setup surface, not the finished downstream integration
  • any later package or package 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 link to open (the connectUrl, or https://app.minion.codes/app/secrets)
  • what provider settings or redirect URI to register (exactly https://app.minion.codes/oauth/callback)
  • that you are waiting for confirmation before building the dependent package or package 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 package app that assumes a non-existent secret or integration
  • treating a rendered app as success when the first authenticated API call fails
  • building a package-app OAuth callback flow by default instead of the standard Integrations page
  • skipping the authenticated smoke test after the user completes setup
  • treating a connected OAuth integration as a pre-built product API package, or continuing to call Gmail, Calendar and similar APIs by hand in execute instead of writing a helpers package