SOAP Broker Direction for Passthrough SOAP Services

Overview

The SOAP Broker direction configures the platform to act as a passthrough proxy for an existing SOAP service. In this mode, the platform receives a SOAP request, forwards the identical request to the designated backend, and returns the backend's response to the original caller, all without transformation.

The primary purpose of the SOAP Broker is to provide visibility and control over existing SOAP traffic. By routing calls through the platform, API publishers gain access to traffic logs, per-operation metrics, and access control policies for services that they are not yet ready to modernize or modify. This allows for gathering baseline usage data, enforcing security, and gaining operational insight into legacy systems.

The SOAP Broker is one of three operational "directions" for a service, configured during onboarding. It is distinct from the Publish direction (which creates a REST facade for a SOAP backend) and the Consume direction (which creates a SOAP facade for a REST backend).

When to use SOAP Broker

Use the SOAP Broker direction when the service contract must remain unchanged. Common scenarios include:

• Adding traffic logs, latency metrics, error rate monitoring, or per-operation volume tracking to an existing SOAP service.
• Identifying and restricting which client systems are calling a service before modifying its contract.
• Gathering evidence of real-world usage—which operations are used, by whom, and how often—to inform a future migration plan.
• Applying policy and gaining visibility for a third-party vendor or partner service that cannot be modified.

If the goal is to expose a SOAP backend via a modern REST/OpenAPI interface, use the Publish direction instead. If a backend has been migrated to REST and legacy SOAP clients must continue to function, use the Consume direction.

How it works

The SOAP Broker forwards messages byte-for-byte. It does not parse and re-serialize the SOAP envelope, ensuring that the message content, structure, and encoding are preserved exactly as sent by the consumer.

The following sequence diagram illustrates the data flow for a single request:

sequenceDiagram
    participant Consumer as API Consumer
    participant Broker as Platform (SOAP Broker)
    participant Backend as SOAP Backend

    Consumer->>+Broker: SOAP Request (with Consumer Auth)
    Note over Broker: Strips inbound Authorization header
    Note over Broker: Adds configured backend credential
    Note over Broker: Adds/Propagates Correlation ID
    Broker->>+Backend: SOAP Request (byte-for-byte body)
    Backend-->>-Broker: SOAP Response / Fault
    Broker-->>-Consumer: SOAP Response / Fault (with Correlation ID)

Message Preservation

The broker is designed to be transparent to the message payload and most metadata.

Message Modifications

Two specific modifications are intentionally made to every request and response:

1. Backend credentials are replaced. The inbound Authorization header from the API consumer is always stripped. The platform then inserts the backend credential configured for the service. This prevents a consumer from presenting its own credentials directly to the backend system.
2. A correlation header is added. The platform injects a correlation ID into responses and logs to enable end-to-end tracing. If the initial request from the consumer already contains a correlation ID, that ID is honored and propagated instead of being overwritten.

Observability

By routing traffic through the platform, a brokered service gains access to standard operational features:

• Traffic Logs: Includes traces of request and response payloads.
• Metrics: Dashboards display volume, latency, and error rates on a per-operation basis.
• Attribution: Logs and metrics associate each call with a specific consumer and operation.

Operation identity is determined primarily from the SOAPAction header. If this header is not present, the platform performs a bounded read of the beginning of the message to identify the operation by the name of the first element inside the SOAP body. This read does not alter the forwarded message bytes.

Caller Access Control

The broker can enforce access control for backend services that may lack it. Each brokered service is configured with one of two access modes:

• Any internal system (Default): The service accepts calls from any source it is reachable from.
• Only the addresses I grant: The service accepts calls only from a specific list of source addresses.

Limits

• Message Size: The maximum size for a single request is 30 MB.
• Routing: Routing is based on the request's address (path). A single brokered service endpoint corresponds to a single backend endpoint. The broker does not route requests to different backends based on SOAPAction or message content.
• Message-Level Security: The broker does not process message-level security protocols. Inbound WS-Security, WS-ReliableMessaging, or WS-AtomicTransaction headers are forwarded as opaque bytes and are not verified, decrypted, or acted upon.

Troubleshooting

For a complete list of platform errors, see the error code reference documentation.

See Also

• Onboarding overview: Describes the three service directions (Publish, Consume, Broker) and provides guidance on choosing the correct one.
• Consume direction: Explains the inverse case of creating a SOAP facade for a REST backend.
• Observability dashboards: Details where traffic metrics and performance data for brokered services are displayed.
• Logs and tracing: Covers how to use correlation IDs to follow a brokered call's lifecycle across multiple systems.

All SOAP-to-REST docs