invokationGive each connection a configuration boundary
A company provider connection such as stripe.production or sendgrid.production needs no enterprise-client identity. It binds an adapter, protected credential version, authentication strategy, token-lifecycle policy, environment, execution policy, and route. Client-specific connections add customer configuration to that same model.
Your product should be able to ask for records.list without choosing a SOAP envelope, interpreting a provider-specific status code, or knowing which outbound addresses an enterprise approved. A connection profile is the boundary that contains those differences.
The operation belongs to your application. In our fictional example, its input is a resource and a limit; its output is a list of normalized records with an optional continuation cursor. These fields demonstrate a vendor-defined contract, not a universal Invokation data model.
Template, profile, environment: three different things
An adapter template describes reusable implementation behavior: how to construct requests, validate input, parse a response, and classify failures. A template might implement a particular REST interface or a documented SOAP service. Sharing a template does not mean sharing credentials or customer data.
A customer profile binds an adapter version to an endpoint, mappings, credentials, supported operations, and a connectivity policy. Client Alpha and Client Beta can implement the same application operation through different adapters. Client Gamma can explicitly decline an action its gateway does not expose.
An environment is a separate operating context. Staging should have its own profile ID, credential references, destination, and route. Promoting configuration should require a deliberate review of every environment-specific reference, rather than copying a live secret into a fixture.
A profile can contain static-key injection, an approved OAuth token endpoint, or documented custom token acquisition. Cache scope and renewal coordination follow the connection and environment. Read managed authentication for the credential boundary.
Map meaning, not just field names
Alpha’s account_name and Beta’s AccountLabel can both map to displayName. Their identifiers may still have different scopes. Their status enums may describe different business states. Your adapter needs to decide whether a source value is representable in the agreed output.
A source status of archived should produce a mapping-validation failure if the application contract only understands active and inactive and no approved interpretation exists. Silently guessing creates apparently successful data that can cause a much later failure.
Pagination also belongs in the adapter. An opaque vendor cursor can encode a page number or gateway continuation token, but callers need documented expiry and stability behavior. A profile should expose capability limits rather than pretending all destinations offer identical sorting, filtering, or writes.
Test the contract before promoting the profile
Fixtures should cover a valid record, an empty page, a missing required field, an unknown enum, an expired credential, rate limiting, and an unsupported action. Keep them synthetic or carefully redacted. A happy-path fixture alone says little about operational readiness.
The workflow combines local tests with a customer-approved sandbox check. Configuration lives in Git; CI validates contracts and mappings; an authorized operator selects the production references. Tests against a sandbox are useful evidence, but cannot substitute for the enterprise approving production routing and access.
Change versions with a recovery plan
Pin the adapter and mapping version in each profile. Test a proposed version against existing fixtures and add fixtures for the new behavior. Record who promoted it, the environment, and the reason. A production change can be breaking even when its configuration diff looks small.
Run history should retain the versioned configuration reference used for each attempt. Replay uses that original version, unless an operator explicitly chooses and reviews a migration. Keeping audit metadata does not require exposing secret values or retaining unrestricted payloads.
Profiles reduce branching inside the vendor application; they do not eliminate adapter maintenance. Someone still owns upstream changes, mapping decisions, certificates, OAuth scopes, and the escalation path when a customer system changes.
Follow the standardization guide for contract design, or see the onboarding sequence for the handover around a new client.