larsggu.me › Guide

The integration lifecycle

Five stages every integration passes through, in order, with the reference entry that governs each one. Nothing here is specific to a product; the stages are the same whether the two sides are two vendors, a vendor and a customer, or two systems inside one organisation.

1. Fit

Establishing what the integration is for

Before any credential is issued, the two sides have to agree on what data moves, in which direction, how promptly, and what happens when it cannot move. Most of the difficulty later traces to one of those four being left implicit at this stage.

The question that settles most of the rest is whether the receiving side needs to know within seconds or within a day. Seconds means events pushed as they occur, with everything the webhook delivery entry describes: signatures, redelivery and a parking behaviour. A day means a scheduled read, which is markedly simpler to operate and should be preferred whenever the requirement genuinely allows it.

The second question is what the integration is allowed to do rather than what it needs to do today. Scopes granted at this point tend to persist, and a permission that was convenient during the first week is difficult to withdraw once code depends on it.

2. Credentials

Issuing something that can be withdrawn

Whatever authenticates the integration must be revocable independently of everything else, which rules out reusing a person’s login. Where the integration acts for an organisation rather than a person, the client credentials grant is the fitting mechanism; where it acts for a person, the authorization code flow is.

The credential is issued with the narrowest scope that lets the agreed work happen, and it is stored where it can be rotated without a redeploy. A secret held in a build artefact travels wherever the artefact travels, which is ordinarily further than intended.

Rotation is planned at issue rather than after an incident. That means the receiving side accepts two valid credentials during an overlap window, so the change can be made without a coordinated outage.

3. Build

Writing the side that consumes

The consuming side is written on three assumptions: that any request may be repeated, that any response may be a failure, and that the shape of a response may gain fields without notice. The idempotency key, error envelope and API versioning entries each cover one of those.

Reads follow the cursor pagination contract, ending on the absence of a next cursor rather than on a short page. Writes carry an idempotency key generated per logical attempt. Failures are handled by branching on the stable type in the error envelope rather than on the message text.

If events are pushed, the receiver acknowledges as soon as the event is durably written and does the work afterwards, and it verifies the signature against the exact bytes it received.

4. Operate

Keeping it correct while it runs

An integration that works on the day it ships fails later for a small number of recurring reasons: a credential expired, a limit was reached, a version was retired, or a change of personnel removed the only person who knew it existed.

The first three are observable. Rate limit headers show the allowance shrinking before it is spent; deprecation headers announce retirement on the responses of the version being retired; token expiry is a scheduled event rather than an alert. Watching those three removes most unplanned interruptions.

The fourth is addressed by writing down what the integration does, which credential it holds, what breaks if it stops, and where its audit events land. An integration nobody can describe is one nobody can safely turn off.

5. Decommission

Ending it deliberately

Integrations are ordinarily abandoned rather than ended, which leaves a live credential attached to a system nobody is watching. Ending one deliberately means revoking the credential first, then removing the registered receiver so deliveries stop being attempted, then retaining the audit events for as long as the obligation on them runs.

Where accounts were provisioned through the integration, they are deactivated rather than deleted, for the reason the SCIM provisioning entry gives: a deleted record detaches every past action from whoever took it.

The final step is to confirm that nothing still calls the interface, which the audit events answer directly. A quiet log after the revocation is the evidence that the decommission is complete.

Topic: Operations. Last modified 2026-09-06.