Integrate through published contracts
Builders consume published SDKs and documented service surfaces. Two anti-patterns are explicitly out of bounds: importing a private implementation package from another team, and treating a marketing route as an operational API. The first couples you to internals that can change without notice; the second couples you to a surface that was never a contract. The API reference overview maps what is published.
The boundary checklist
Every integration against the platform should satisfy all seven of these — they are the difference between "the request returned 200" and "the integration is done":
- Identify the authoritative source and the shared record being updated. If two systems can disagree about the fact, name the winner before you write anything. Data fabric orientation is the worksheet for this.
- Carry explicit brand context and authenticated identity on every call. Context is never inferred from a URL, a payload field, or a previous request — it comes from the credentialed session, exactly as Triangle sessions & tokens describes.
- Validate authorization for the requested operation, not just for the session. A valid token for brand A says nothing about brand B.
- Apply current policy and required approval gates. An integration that triggers an irreversible action routes through the same gates an operator would — see approval gates.
- Make retries idempotent so repeated delivery does not duplicate work. Events on the platform are delivered at least once; idempotency at the consumer is the contract's other half. Webhooks & the event substrate covers signatures, retries, and replay.
- Preserve correlation and outcome evidence for operator review — request ids, delivery attempts, and results an operator can reconstruct later.
- Stop safely when authority, policy, source freshness, or dependency state is uncertain. A paused integration that pages an operator is healthy; one that proceeds on a guess is a liability with a retry loop.
Warning
An integration is complete when operators can verify its authority, current state, failure behavior, and evidence — not merely when a request returns successfully.
Failure modes we design against
Three failure shapes account for most integration damage, and the checklist exists because of them:
- The silent cross-brand read. A query that "worked" in testing because the test context was broad, then reads outside its brand in production. The database boundary makes this a loud failure instead — see database isolation mechanics — but the correct posture is never relying on a broad context in the first place.
- The duplicate side effect. A retried write that executes twice because the consumer assumed exactly-once delivery. Platform events are at-least-once; idempotency keys and deduplication at the consumer are the only correct answer.
- The optimistic irreversible. An automation that issues the refund, sends the message, or deletes the record on the assumption that approval is a formality. Irreversible classes are gated by policy, and an integration that routes around the gate is out of contract regardless of intent.
Reviewing an integration before it ships
Before an integration goes live, an operator should be able to answer: which brand contexts can it touch, which records can it write, which actions can it trigger, what happens when its credentials are revoked, and where its activity appears in the audit trail. If any answer is "we would have to check the code," the integration is not ready — the answers belong in its operating documentation.
Public reference boundary
This documentation describes integration discipline, not a production endpoint catalog. Credentials, endpoint details, live schemas, and environment-specific procedures remain in authenticated developer access.