Drafting integration code with AI: a safe workflow
A safe workflow for drafting integration code with AI: prototype, senior review, tests, then ship, plus what you should never auto-merge.
An engineer pastes a partner's OpenAPI spec into an assistant, gets a working client in twenty minutes, and feels done. Then someone notices the refresh token is logged, the webhook handler is not idempotent, and a 429 is treated as a hard failure. The draft was fast. It was not ready to touch customer data.
The model is good at the blank-file stage and confident about the parts that hurt in production: secrets, retries, tenancy, error mapping. Speed without a review gate produces code that looks finished and is subtly wrong. The safe workflow is prototype, senior review, tests, then ship. It pairs with AI tooling for partnerships and SaaS integration strategy.
The 60-second version
- AI is strong at first drafts of integration code and weak at the parts that touch money, identity, and other people's data. Treat the output as a spike, not a ship.
- The workflow is prototype, senior review, tests, then ship. Skip a step and you are merging a demo.
- The prototype is allowed to be messy. Hardcoded sandboxes, incomplete error paths, and missing retries are fine in a spike. They are not fine in the PR that goes to production.
- Senior review is not a skim. Auth, secrets, tenancy, retries, idempotency, and data mapping get a line-by-line pass, because those are the failure modes partners and customers feel.
- Tests must exist before merge: auth, the happy path, the error path, idempotency, and at least one fixture from the partner's real sandbox.
- Never auto-merge AI-written code that handles credentials, webhooks, writes, or PII. Those classes fail closed: a human ships them.
- A senior human owns the ship. Faster prototypes do not change the roadmap. The model removes the blank-file cost. It does not own production.
Why AI drafts integration code well, and where it fails
Partner integrations are a good fit for an assistant at the start of the build, for boring structural reasons. The work is often well specified: an OpenAPI document, a webhook catalog, an OAuth sequence, a handful of resources. That is the kind of structured surface models handle well. A senior engineer staring at a blank repository spends most of the first day recreating a client, types, and a polling loop they have written a dozen times. The assistant does that day in an hour.
Where it fails is also structural. Integration code sits on a trust boundary. It stores tokens, receives signed webhooks, maps someone else's records onto yours, and retries against an API you do not control. The model has no production memory of the last partner who rotated a signing secret without notice, or of the customer who double-posted the same event. It will invent a retry that is not idempotent, a log line that prints a bearer token, or a mapping that drops a required field because the example in the docs omitted it.
| What the model drafts well | What it routinely gets wrong |
|---|---|
| Client SDKs, types, and request builders | Token storage, rotation, and secret handling |
| Happy-path handlers from an OpenAPI spec | Idempotency, replay, and partial-batch failure |
| First-pass tests against fixtures | Auth edge cases and partner-specific error codes |
| Boilerplate pagination and rate-limit stubs | Tenancy: whose data is in this request |
| Spike code against a sandbox | Production mapping, retries, and observability |
Use the model to collapse the slow start. Do not let it own anything that can leak a token, write the wrong tenant's data, or drop a webhook. Same split as MCP security: generous on drafts, strict on writes and secrets.
The workflow: prototype, review, test, ship
The workflow is four steps, in order, with a named owner at each gate. Reordering them is how teams ship a sandbox spike as if it were an integration.
1. Prototype with AI. Give the assistant the partner's docs or OpenAPI spec, the scope of the job (not the whole API), and a sandbox. The output is a spike: a client, a thin handler, and enough of a path to prove the partner's API can do what the scope assumes. Time-box it. The point is a feasibility answer, not a pull request.
2. Senior review. A person who has shipped integrations before reads the draft against a checklist, not against "does it compile." They are looking for auth, secrets, tenancy, retries, mapping, and anything the model invented that is not in the partner's docs. If the reviewer did not build the spike, even better. Fresh eyes catch the confident wrongness.
3. Tests. Auth, happy path, error path, idempotency, and at least one recorded fixture from the partner sandbox. Tests written only against the model's imagined responses will pass and still fail in the partner's environment. The fixture is the contract.
4. Ship. A human merges. CI can require the tests. CI should not be allowed to merge the PR because an assistant opened it and the build is green. Green on synthetic tests is not the same as safe on a partner API.
| Step | Owner | Done when |
|---|---|---|
| Prototype | Engineer plus assistant | The spike proves or kills the scope against sandbox |
| Senior review | A senior engineer, preferably not the author | Auth, secrets, tenancy, retries, and mapping pass the checklist |
| Tests | The author, reviewed | Auth, happy path, errors, idempotency, and a real fixture are green |
| Ship | The senior owner | A human merges; the integration has a named maintainer |
This is still an integration project. The prototype may skip retries, metrics, and full pagination. It may not commit secrets, ignore tenancy, or call production "just to see." If the spike proves the scope, rewrite those gaps before review.
The senior review checklist
Review is where the workflow earns its keep. A skim for style will miss the bugs that matter. The reviewer should be able to answer each of the following from the diff, or the PR waits.
Auth and secrets. Where tokens live, how they refresh, who can read them, and whether logs ever print them. A common model mistake is logging the refresh token or storing it in plaintext.
Tenancy. For every request and webhook, whose data is this. Thread a tenant id from the credential to the write. A shared process-wide token is a stop.
Retries and idempotency. What happens on 429, 5xx, timeout, and a duplicate webhook. Retrying a non-idempotent POST duplicates records. Handlers key on event id.
Mapping and defaults. Persist only fields from the spec or a recorded fixture. Invented required fields fail certification. Dropped ones fail after a quiet launch.
Blast radius. Fail one bad record loudly. Model drafts often fail the whole job, or swallow the error and continue with a partial write nobody sees.
Observability. Request id, partner error code, tenant correlation. More than console.log("failed"), less than a full platform in the first PR.
The CWE Top 25 is a useful independent prompt for this review, even though it is not AI-specific. Injection, broken auth, and sensitive data exposure show up in integration drafts for the same reasons they show up in hand-written code: the happy path was easy and the boundary was not. OWASP's Top 10 for LLM applications adds the model-specific risks, prompt injection into your tooling, data leakage into the prompt, and over-reliance on the output. Both lists belong in the review, not in a slide.
Tests that must exist before merge
A green build on tests the model wrote against responses the model invented is not coverage. It is a circular compliment. Require a small, specific set before anyone hits merge.
Auth tests. Token fetch, refresh, expiry, and a 401 that forces re-auth. If the partner uses rotating webhook secrets, a test that rejects a bad signature and accepts a good one.
Happy path against a fixture. Record a real sandbox response (redact secrets) and replay it. The mapping should survive the partner's actual field names, nulls, and extra fields you do not use.
Error path. 422 with a partner message, 429 with Retry-After, 5xx with backoff, timeout. Assert you do not retry forever, and that you do not retry non-idempotent writes without a key.
Idempotency. Deliver the same webhook twice. The second delivery must not create a second record. Replay is not a rare event; it is how webhook systems work.
A sandbox smoke test, gated. One live call against the partner sandbox in CI or in a manual pre-merge check, with secrets in a vault, not in the workflow file. This is the test that catches "the spec is stale."
You need those five, named, and failing when someone "simplifies" retry logic. After launch, integration monitoring covers schema drift, silent sync gaps, and latency creep. Tests protect the merge. Monitoring protects the months after.
What to never auto-merge
Auto-merge is the tempting last cut. The assistant opens the PR, CI is green, a bot merges. For internal refactors of your own types, maybe. For integration code, no. Write the never-list so nobody has to argue about it during a fire.
Never auto-merge AI-written changes that:
- Create, store, refresh, or log credentials, tokens, signing secrets, or API keys.
- Handle inbound webhooks or callbacks, including signature checks and replay.
- Perform writes in the partner or in your system on a partner event (creates, updates, deletes, money movement, permission changes).
- Touch PII mapping, retention, or anything that could send customer data to a new destination.
- Change retry, backoff, or rate-limit behavior on a live integration.
- Widen scopes, add endpoints, or follow a new redirect in an OAuth flow.
Those classes fail closed. A human reads them, even when the diff is "small." Small auth diffs are how scopes get over-granted.
A useful operational rule: the assistant may open PRs. Merging is a senior permission, and the never-list is enforced in CODEOWNERS or the equivalent, not in a wiki nobody opens. If you use generated tests, they do not count as the required suite until a person has seen the fixtures.
Integration versioning makes this stricter after launch. An AI-proposed bump that "just" changes a payload shape can break a partner's certification. Version changes are writes to a contract. They get a human.
Faster drafts do not change the rest of the tech partnership: scope, legal, app review, enablement, maintenance. Customer pull still ranks the list. Every shipped integration still needs a named owner. The assistant is a junior pair with no production scars, not a release manager.
Common mistakes, and the fix
Merging the spike because the demo worked. The fix: keep spike and ship on different branches, with an explicit rewrite of secrets, retries, and mapping before review. A demo against sandbox is a feasibility answer, not a production PR.
Letting CI auto-merge a green AI pull request. The fix: CODEOWNERS on auth, webhooks, writes, and PII paths, plus a human merge for those classes. Green tests on invented fixtures are not a ship signal.
Reviewing for style instead of for the boundary. The fix: use the checklist (auth, tenancy, retries, mapping, blast radius, observability). A tidy client with a logged refresh token is a failed review.
Trusting tests the model wrote against responses it invented. The fix: require a recorded sandbox fixture and the five test classes above. Add a gated live smoke test for the partner environment.
Pasting production payloads into the prompt. The fix: sandbox data only, redacted fixtures. The workflow is for code, not for copying live PII into a vendor.
Treating faster drafts as a license to build every connector. The fix: keep the same integration strategy filter. Speed at the keyboard does not add maintenance capacity.
FAQ
Can AI write our integration end to end? It can write a strong first draft. A senior engineer still reviews, tests with real fixtures, and merges, because the code stores tokens and maps customer data.
What should we never auto-merge? Credentials, inbound webhooks, writes, PII mapping, live retry changes, and OAuth scope changes. An assistant may open the PR. A person ships it.
How much review does a small team actually need? A line-by-line pass on auth, tenancy, retries, mapping, and observability. Style nits can wait. The boundary cannot.
Do we still need a sandbox if the assistant read the OpenAPI spec? Yes. Specs lag. A fixture recorded from sandbox is the contract your tests should bind to.
Is it safe to paste partner docs into an AI tool? Public docs and sandbox examples, usually. Confidential specs, customer payloads, and tokens, no. Check retention and training policy.
How does this change after the integration is live? Same workflow, higher bar. Version and mapping changes still get a human merge, then monitoring watches production.
The short version
Draft integration code with AI the way you would pair with a fast junior: let it take the blank file, then put a senior on the boundary. Prototype against a sandbox to prove the scope. Review auth, secrets, tenancy, retries, mapping, and blast radius. Require tests on auth, the happy path, errors, idempotency, and a recorded fixture. Ship with a human merge.
Never auto-merge credentials, webhooks, writes, PII mapping, live retry changes, or OAuth scope widening. Faster spikes do not change which integrations you should maintain. Production still needs an owner.
If you want help deciding which integrations to spike first, that is exactly what a Partner Audit is for. We review your product, API, and partner potential, then define what to build, who to approach, and how to ship it.