The split is direction, not function. A Listener has to expose an endpoint and accept inbound connections; a Caller has to reach out and manage connections, timeouts, and response handling. Splitting them in the platform lets each adapter focus on the work its side requires.

Bound to a receive port, the API adapter turns the port into an addressable HTTP endpoint. External callers issue requests against the configured path; the adapter accepts them, runs the receive port's inbound stages, and publishes the resulting message to the bus.

Both modes are supported. One-way returns immediately after publishing; two-way holds the caller's connection open and waits for a matching response message on the bus.

In two-way mode on the receive side, the adapter has to know which bus message is the response to the request it just received. That is the job of the receive port's Response Subscription Expression: a Boolean predicate the bus evaluates against every published message; the first match becomes the response delivered back to the caller.

The expression is evaluated in the same engine used by send/loopback/null port subscriptions, with one important addition: it can reference values that belong to the original inbound request. The most useful of these is a correlation token (a request id, a unique header, a generated GUID) assigned to a variable at the start of the receive port's inbound flow and matched on the outbound side of whichever port produces the response.

Bound to a send port, the API adapter dispatches an HTTP request to a configured endpoint. The send port carries the request configuration (method, URL, headers, body) and the adapter handles the dispatch and response.

One-way mode fires the request and continues; the HTTP status is checked for success/failure but the response body is discarded. Two-way mode waits for the HTTP response and republishes it to the bus as a payload message, ready for a downstream port to subscribe to.

The send port configures the outbound request the API Caller will issue. URL, headers, and body are plain strings templated with {{…}} bindings: promoted properties, variables, constants, and {{Config.*}}. Body extractions ({{Message.Body}}.XPath) are not evaluated in adapter fields; promote the value on the message type or capture it into a variable and bind that.

The API adapter pairs with an API Authentication, and the two directions take different Definitions, because direction decides who sets the rules: calling out, the remote API dictates how you must authenticate; listening, you dictate what callers must present:

• Send side (API Caller): the Authentication presents credentials on the outbound request. The adapter injects them automatically, never set an Authorization header by hand on the Request Headers list; it will be overwritten.
• Receive side (API Listener): the Authentication validates credentials presented by inbound callers. Where an Authentication is required and the inbound credential is missing or invalid, the listener returns 401 without invoking the rest of the receive port.

On the port, the pairing is made in the adapter configuration dialog through two fields. Auth Config Type chooses between Static, which pins the port to one named Authentication, and Dynamic, which resolves the Authentication name at runtime from a {{ }} binding, so a single port can present a different credential per message, one delivery port serving many partners, each with its own login, instead of a cloned port per login. Auth Config then holds the static pick or the dynamic expression.

A Listener’s Authentication is built on the API Listener Token Definition: its Partner Config section carries the Token inbound callers must present. A Caller’s Authentication is built on one of two Definitions, matching what the remote API demands. API Basic Authentication (Basic AuthConfig) carries a Username and Password. API Bearer Token (Bearer AuthConfig) carries a Login URL, Refresh Token URL, Token JSON Path, Refresh Token JSON Path, Username, and Password: the adapter logs in, lifts the token out of the login response with the JSON path, presents it as the Bearer Authorization header, and renews it through the refresh pair. Further shapes arrive as partner APIs demand them.

Every API Listener in the solution is hosted under the same base URL, there is one ingress for the whole environment. The path alone does not tell the runtime which receive port a request belongs to, so the listener routes on the inbound credential and headers instead. Three things together select the destination port:

• The App header, whose value is the target Application’s namespace, this is what narrows an inbound request to one Application.
• The Authentication presented on the request, the credential is part of the routing key, not just an access check.
• Any additional matching headers the receive port declares, the tie-breaker described below.

The App header plus the Authentication is enough only while an Application has a single API Listener. The moment two API Listeners live in the same Application, that pair no longer distinguishes them, an inbound request would satisfy both, so each Listener must declare an extra header that makes it unique. The header name is your choice; a clear convention is a Purpose header with a per-port value, e.g. Purpose: Order on one and Purpose: Invoice on another.

That full combination, App namespace, Authentication, and any distinguishing headers, has to be unique. If two running receive ports declare the same combination, an inbound request matches both and the runtime cannot decide where to route it. To prevent it, the combination is validated for uniqueness across the whole system, not just within an Application, at the moment a port is started.

• Stopped, allowed. A stopped port is inert and takes no part in routing, so a colliding combination can sit in a stopped port without conflict.
• Start, blocked. Starting a port whose combination already belongs to another running port fails validation; the port stays stopped with nothing lost.

Fields differ by side. The Listener set matches the current dialog; the Caller set is still to be verified against the running product.