You're a Guest, Not the Architect

The single most important mental shift when integrating into a customer's environment: you don't own this system, and your job is to change as little about how it behaves as possible while extracting the value the engagement needs. Every design decision should default toward the least invasive option — read-only access before write access, a new isolated service before a modification to an existing one, and additive changes before anything that touches existing behavior other teams depend on.

The Reality of Legacy APIs

Documentation for internal enterprise systems is often stale, incomplete, or simply wrong about current behavior. A few habits that hold up:

  • Treat the documentation as a hypothesis, not a fact — verify actual behavior against a test account before building logic that depends on documented behavior, especially for error responses and edge cases.
  • Prefer read replicas or exports over hitting production APIs directly for anything bulk or repeated — a nightly export to an isolated location is both gentler on the source system and easier to reason about than a live query pattern nobody has load-tested.
  • Wrap every external call in an explicit boundary — a thin adapter layer that owns retries, timeouts, and error translation, so the rest of the system never talks to the legacy quirks directly. When (not if) the legacy behavior changes, you fix one file.
  • Assume rate limits exist even when undocumented — build exponential backoff and jittered retry from day one. Discovering a rate limit in production, mid-demo, is an avoidable embarrassment.

SSO and Identity: The Quiet Source of Delays

Enterprise single sign-on setups routinely behave differently for interactive human logins than for the service accounts an integration needs, and this mismatch is one of the most common causes of stalled timelines. Confirm early — in week one, not week four — whether the integration needs a dedicated service account, what identity provider mediates it, and who inside the customer's org can actually provision one. This is frequently a security or IT approval, not an engineering decision, and approval queues can run longer than the engagement's entire prototype phase if not started early.

Never become the sole credential holder

Credentials for anything touching customer data should be provisioned by the customer, into infrastructure the customer controls — their own secrets manager, scoped to the minimum access the integration needs. An FDE holding a customer's only copy of a production API key, in a personal password manager or a laptop .env file, is a security and business-continuity risk that should be flagged and corrected the moment it's noticed.

When There's No API at All

Some systems genuinely have no programmatic interface — a desktop application with no export function, a mainframe terminal, a workflow that only exists as a human clicking through a UI. In roughly that order of preference: ask whether a scheduled export or reporting feature already exists that a human just isn't using programmatically; check whether the customer already licenses an integration or middleware product (an iPaaS, an RPA tool) that solves this class of problem; and only as a last resort, build a narrow extraction layer of your own — clearly documented as technical debt, with an explicit plan to revisit it before the system goes to production ownership (see Article 9 on production handoff).

Working Alongside the Platform Team

The customer's platform or IT team did not ask for this integration, inherited systems they may not fully trust either, and will be the ones supporting whatever you build after you leave. Treating them as a partner rather than an obstacle pays off directly: loop them into design decisions that touch their systems before those decisions are final, not after; ask what's broken or fragile about the system before you build against it — they usually know exactly where the bodies are buried; and document the integration for their maintenance, not just for your own use during the engagement.

Testing Integrations Without a Staging Environment

Many enterprise systems lack a proper staging environment that mirrors production closely enough to trust. When that's the reality, build a synthetic test harness that mimics the real system's response shapes and known edge cases — timeouts, partial failures, malformed records — and run against it before any production connection. It's extra upfront work, but far cheaper than debugging an integration failure live against a system you can't safely poke at.

Frequently Asked Questions

What do you do when a customer's legacy system has no usable API?
Look for a lower-friction path before building a scraper or a fragile UI-automation layer: scheduled file exports, a database read replica, or a middleware product the customer already licenses. If none exist, build the narrowest possible extraction layer and treat it explicitly as technical debt to revisit before production handoff.

Who should own credentials and API keys during an engagement?
The customer, always. Credentials should be provisioned by the customer's own identity and access system into a secrets manager they control, with access scoped to only what the integration needs. An FDE should never be the sole holder of a customer's production credentials.

How do you handle a customer's undocumented rate limits?
Assume they exist even when nobody can quote a number, and build backoff and retry logic from the start rather than adding it after the first outage. Ask the platform team directly, but plan for the answer to be wrong or incomplete — legacy systems' actual limits often differ from what's documented.