D2.5 · Review of the API Mediation proposal

Work stream	WS 2 — Target State Architecture
SOW source	Not in Schedule "A" — client-requested addition, delivered under WS 2 activity 4 and the §7 RACI line "Provide architecture POV and recommendations"
Status	🟡 In progress
Indicative window	Weeks 2–4

Why this deliverable exists

Manulife's team holds that a unified API layer is needed to support the dashboard, and has given us a proposal circulated in March 2025 to review: API Mediation. This page is that review.

It is not a Schedule "A" deliverable. It is delivered under the WS 2 activity that asks us to "identify architectural decisions, trade offs, dependencies, constraints and areas requiring further client decision or validation", and under the §7 RACI line that makes architecture POV and recommendations Konrad's to produce. Integration and API architecture is a named WS 2 target-state domain, and this proposal is the only client-authored statement of enterprise position in it.

Scope guard. SOW Schedule "A" §3.0 puts "detailed assessment of individual applications, platforms or technologies" and "implementation-level solution design — API/microservice/ integration specifications" out of scope. This review assesses the proposal's fit with the target state and its consequences for the Unified Portal. It does not grade the vendor, write gateway policy, or specify APIs. Where a finding needs implementation work to resolve, we name the work and stop.

The short version

The proposal is directionally right and structurally incomplete. Its two-tier split — centralized Inter layer for enterprise cross-cutting concerns, federated Intra layer service mesh per line of business — is the correct shape for an estate with six lines of business, two gateways and ~4,200 API operations. It also already contains, as a mandatory capability, the single mechanism that would close the most serious finding against the Unified Portal MVP.

Three things have to change before it can carry the dashboard.

Each area is argued as a standing recommendation under theme R4 · API mediation: area 1 is R4.1, area 2 is R4.2, area 3 is R4.3. This page carries the evidence and the scenarios; the recommendation pages carry the position and what we are not recommending.

Area 3 bundles three decisions and R4.3 answers one of them. Its sequencing position — which domain the layer mediates first — is R4.3's. The other two are decisions the deck itself frames as options and leaves open, so they sit in theme R6 · Open decisions: whether the model is centralized, federated or the two-tier split slide 4 draws is R6.2, and whether the layer orchestrates is R6.3. The third — what happens to ~4,200 already-registered operations — stays open question 30.

#	Area	Recommendation	One line
1	Latency, availability and load budget	R4.1	It adds two synchronous hops per call to an eight-call fan-out that already misses its availability target by two orders of magnitude, and marks rate limiting optional
2	Authorization and data handling	R4.2	It mediates transport, not authorization; its mandatory JWT Exchange is never connected to the problem it solves, and mandatory logging with no redaction capability creates a new copy of Highly Confidential data
3	Boundary, orchestration and migration	R4.3 · R6.2 · R6.3	"Centralized vs federated" is the wrong axis; the real decisions are where the Inter/Intra boundary sits, whether the layer orchestrates, and how ~4,200 existing operations coexist

---

Area 1

Every mediated hop is a synchronous dependency, and this path has no budget left

Concern. The segment assessment's C-01 computes the MVP's composite availability at 98.71% — thirteen hard dependencies at a realistic 99.9% each — against a committed 99.99%, or 52.6 minutes a year. That is roughly 129× the downtime the ADS commits to. Domain L sizes the load: eight calls per page load, one BU Mapping call plus seven BU Data API calls, against a single documented downstream ceiling of 25 TPS at FCC.

The proposal routes each of those eight calls through the Inter API Mediation Layer and then the target line of business's Intra layer service mesh sidecar. Two new synchronous, policy-enforcing hops per call. Sixteen new hops per dashboard render.

The arithmetic is unforgiving and does not depend on any assumption about Manulife's gateways:

Added tiers	Per-tier availability	Added annual downtime	Against a 52.6 min budget
2	99.9%	17.5 h	20× the entire budget
2	99.99%	1.75 h	2× the entire budget

Two tiers at four nines each consume twice the whole annual error budget before any application code runs. The proposal publishes no per-hop latency budget and no availability allocation, while the ADS commits to 99% of API responses under 800 ms, 90% under 300 ms, and 99% of shell pages under 1 s.

The capabilities that would protect this path are marked optional. Slide 5 marks each capability mandatory or optional in its own legend, and all six traffic-management capabilities are optional — rate limiting, throttling, service routing, response caching, IP allow/block list and orchestration. Metrics, request tracing and logging are mandatory. So the layer is required to observe the fan-out and not required to govern it.

There is also nothing in the Inter layer capability matrix for circuit breaking, bulkheading, timeout budgets or retry budgets. Resiliency appears only as a chip inside the per-LOB Intra layer service mesh. The assessment's D-06 finds the BFF is an unmitigated single point of failure with no bulkheading and no per-BU timeout budget; inserting a shared enterprise tier in front of it adds a failure domain without adding a control.

Scenario — Monday 08:00, first login wave after a Sunday-night deploy

Redis is cold. The assessment's D-03 already establishes that the cache cannot shield upstreams on cold start, after deployment, after eviction or on TTL expiry — so every one of these renders reaches every BU API. The ADS's capacity NFR is 20,000 concurrent users.

Each login fires eight calls. Under the proposal each call crosses the Inter gateway and an Intra sidecar. The Wealth path terminates at FCC, documented at 25 TPS with capacity planning marked in progress. Rate limiting at the Inter layer is optional and, being optional, unlikely to be configured on day one.

The first thing that fails is not the dashboard. It is FCC — and with it the existing Wealth servicing traffic that was never part of this programme. The dashboard's blast radius becomes another business unit's production channel, on a Monday morning, with no fallback route because D-01 establishes there isn't one.

Scenario — retry amplification during a brownout

This is the failure mode a mediation layer introduces for free unless it is explicitly designed out.

Assume conservative, sensible defaults at each tier: the Integration API retries a failed call once, the Inter gateway retries once, the Intra sidecar retries once. Independently reasonable; composed, each logical call becomes 2 × 2 × 2 = 8 downstream attempts.

	Per logical call	Per page load (8 calls)
No retries	1	8
Three tiers retrying once each	8	64

A downstream that has slowed but not failed — a GC pause at Group Benefits, a FCC brownout — now receives eight times its normal load at the precise moment it is degrading. The retries arrive because it is slow, and it is slow because the retries arrived. Against FCC's 25 TPS this converts a recoverable brownout into a sustained outage, and the dashboard's own 99.99% commitment guarantees it will be retried aggressively.

What we recommend — R4.3 — R4.2 — R4.1

1. Make rate limiting, throttling and circuit breaking mandatory Inter-layer capabilities on any path that fans out. Expressed as a per-consumer, per-downstream token budget — the Integration API's aggregate claim on FCC is a configured number, not an emergent one. This is the single highest-value change to the proposal, and the mediation layer is the right place for it: better one enforced ceiling than seven BU APIs each defending themselves.
2. Publish a per-hop latency and availability budget that sums to the ADS's commitments, with a named owner per hop. If the arithmetic does not close — and at two added tiers it does not close at 99.99% — then the commitment is wrong, the topology is wrong, or the path must degrade. That is R2.2's argument, and this proposal makes it sharper rather than answering it.
3. Specify a single coordinated retry budget across the three tiers, not per-tier retry policy. Retries at one tier only, with jitter, a global attempt ceiling and a circuit breaker that opens on downstream error rate.
4. Settle JWT introspection policy explicitly. Introspection (RFC 7662) is a synchronous call to the authorization server per request; marked optional, it will be switched on for a Highly Confidential surface and turn the AS into a hard dependency of all eight calls, at 20,000 concurrent sessions. The alternative — local validation against cached JWKS with short token lifetimes — trades revocation lag for availability. Both are defensible; leaving it optional means the trade is made by whoever configures the gateway.

What we need to confirm it

CR-39 — current gateway latency percentiles and the mediation layer's own availability history, if it is deployed anywhere today. Combined with CR-22 and CR-23, that is enough to close the budget.

---

Area 2

It mediates transport, not authorization — and it already contains the mechanism that would

Concern. The assessment's B-01 is the most consequential technical finding in the corpus: customer identity is dropped at the BFF boundary. Both hops authenticate as a service principal, and the ADS's own API table shows the mechanism — GET /api/v1/investments?ciamId=. Customer scope is a query parameter chosen by the caller. The assessment classes this as the canonical OWASP API1 broken-object-level-authorization pattern.

A mediation layer that validates the caller's token and forwards the request unchanged does not fix this. It makes it worse in one specific way: the layer becomes a confused deputy holding an enterprise-scoped credential with a route to every LOB backend. Centralizing a service-principal fan-out concentrates it.

The proposal already mandates the fix and never connects it to the problem. Slide 5 marks JWT Exchange mandatory at the Inter API Mediation Layer, and the authorization server box lists token exchange among its functions. The API landscape shows gb-core-authx already running in Group Benefits as an RFC 8693 token-exchange service. So the capability is mandatory in Manulife's enterprise API architecture, live in Manulife's estate, and demanded by Manulife's own assessment — and absent from the design it would govern.

Worked example — the same request, before and after

Today. The Integration API calls Wealth for customer A:

GET /api/v1/investments?ciamId=CIAM-A
Authorization: Bearer <service-principal JWT>

The investments API cannot refuse. The caller is entitled to call it; the subject is a parameter. Now substitute CIAM-B — by a corrupted row in the manually maintained BU Mapping table (finding B-02), a Redis cache-key collision, or an index bug in the Integration API's fan-out loop. Customer B's holdings render in customer A's dashboard. Nothing anywhere in the path detects it, because from every component's point of view the request was valid.

Under mandatory token exchange. The Integration API presents the customer's CIAM access token plus its own client credential; the Inter layer exchanges them (RFC 8693, subject_token = the customer's token, audience = the target LOB API) and forwards:

GET /api/v1/investments
Authorization: Bearer <exchanged JWT — sub=CIAM-A, aud=wealth-api>

The same substitution now returns 403 at the Wealth API, because the token's subject is not B. The ciamId parameter becomes redundant and can be rejected when it disagrees with sub.

The difference is not that one is more secure in the abstract. It is that the failure becomes a logged, alertable 403 at the system that owns the data instead of a silent wrong-customer disclosure at the system that renders it. That is the whole of B-01, and it is the whole of R1.1.

The proposal's governance box also carries an AuthZ Scopes Catalog — the register that exchange needs to target audiences and scopes per LOB. It exists in the deck and nothing in the deck uses it.

Data protection is drawn on the wrong gateway

Slide 4 lists Data Protection as a capability of the External Egress API gateways only. It is not listed on the Internal API Gateways. The Unified Dashboard's cross-BU aggregation is internal, inter-application traffic — so the one capability that would enforce field-level redaction and classification does not sit on the path carrying Highly Confidential cross-BU balances.

The Message Handling group compounds it: schema validation, input sanitization, message transformation, protocol translation, format translation. No redaction, no masking, no classification tagging anywhere in the capability set.

Mandatory logging at a chokepoint is a new data store

Logging is mandatory at the Inter layer, alongside metrics and request tracing. Logging every request at a central chokepoint, where payloads are customer investment, wealth and portfolio data the ADS itself classifies Highly Confidential, creates a new copy of that data.

The assessment's A-02 logic applies verbatim — "a cache of Highly Confidential data is a data store" — and so do the consequences it names: encryption at rest, key custody, residency, retention, purge and classification. The ADS's residency NFR is that all PII resides in Canada and PII in transit is not accessible outside Canada. The deck's "Enterprise Observability Platform" is unnamed; the ADS names New Relic, PromStack and ADX.

Mandatory logging plus no redaction capability is the combination that guarantees the problem rather than risking it. Domain G already finds no redaction design; E-01 already finds no PIA and no Quebec Law 25 position.

The policy decisioning point has no policies

Policy Enforcement is a mandatory Security capability. The reference architecture's Policy Decisioning Point box lists its contents as "Authorization Server Credentials, Other Credentials" — identical to the Secrets Management box above it. No policy artifact, no policy language, no policy information point, no decision model.

A mandatory enforcement point in front of an undefined decision point enforces nothing. If this PDP is the PingAuthorize PDP named in the June 2026 unified customer architecture, then these two documents describe the same component and neither says so — which is worth more to this engagement than either document alone.

What we recommend

1. Make token exchange mandatory on the aggregation path, not merely mandatory in the deck. The Inter layer exchanges the customer's token for a downstream-audience token per LOB call. The LOB API authorizes on sub. This is the client's own capability, the client's own estate component, and the client's own finding, aligned.
2. Add Data Protection to the Internal API Gateways, and add field-level redaction and data classification tagging to Message Handling. Cross-BU aggregation is internal traffic; that is where the control has to be.
3. Specify the observability data contract before the layer carries production traffic — what is logged, what is redacted at source, where logs reside, under what retention, at what classification. A mediation layer is the best place in the estate to enforce redaction once, centrally. That argument only works if redaction is a capability.
4. Populate the PDP. Name the product, the policy language, the policy information points and the decision model, and state whether it is PingAuthorize. Until then, treat "Policy Enforcement" as an unimplemented capability rather than a control.
5. Use the AuthZ Scopes Catalog as the register for exchange audiences and per-LOB scopes. It is already in the proposal's governance set.

What we need to confirm it

CR-40 — the authorization server and PDP product decisions, the gb-core-authx RFC 8693 contract, and the enterprise observability platform's residency and retention position.

---

Area 3

"Centralized vs federated" is the wrong axis, and the estate has already answered it

Concern. Slide 3 is a fourteen-row comparative study posing centralized against federated as a binary. Slide 4 answers it correctly — both, Inter centralized and Intra federated — and buries that answer under the comparison. The genuine decision is not which model; it is where the Inter/Intra boundary sits, and the proposal gives it one sentence: "coarse-grained, enterprise-level cross-cutting concerns" centrally, "domain or LOB-specific considerations" delegated. There is no rule for adjudicating a capability that could plausibly sit on either side.

Meanwhile the estate already federates, deliberately and in production. The API landscape enumerates two gateways: PIE-APIM shared across 15+ BU tenants with 2,889 operations, and GB-APIM dedicated to Group Benefits with 1,311 operations across 342 APIs — dedicated for a stated reason, the Akamai GTM flow and high-volume claims and member APIs. zOS Connect is exposed through PIE-APIM as a mainframe adapter rather than as a peer gateway. That is hub-and-spoke with a reasoned exception, carrying roughly 4,200 operations today.

The comparative study mentions none of this. It compares centralized and federated management in the abstract, against an estate that has already made the choice and documented why.

The orchestration collision

Orchestration is listed as an Inter-layer traffic-management capability; Transformation and Integration appear on both the External Ingress and Internal gateways. Aggregating several backend calls into one response is precisely what the MVP's Integration API does. Two readings, both consequential, and the deck does not say which is intended:

If the Inter layer orchestrates	If it does not
The Integration API is partly redundant, and the composition boundary moves into a centrally governed, centrally deployed component	The layer is transport plus policy; the Integration API stays, and the proposal's "reduced duplication" benefit does not reach the composition tier at all
A dashboard card change becomes an enterprise gateway change — and the deck annotates the gateway's deploy path "Deploy (manual)" from a management plane it labels "ClickOps"	The governance story is narrower than the deck claims, and cross-BU aggregation logic stays unarbitrated between six lines of business

The first reading is a release-cadence collision across six lines of business with independent release trains, at a chokepoint whose own deployment path is manual. That is the concern R3.1 exists to manage, and the answer determines whether the Unified Portal's Integration API is target-state or interim — which changes what WS 3 sequences and what it costs.

Migration is absent, and it is the whole cost

The proposal has no strangler sequence, no coexistence model, no dual-ingress period, no per-tenant cutover ordering, no deprecation policy, and no position on what happens to the GB-APIM exception. Fronting or migrating ~4,200 operations across 15+ tenants — each with APIM products, subscription keys and ACLs — is a multi-year programme.

The Unified Portal needs eight APIs on a login critical path now, and the experience map maps 42 onto the target homepage. Those are very different problems, and the second does not have to wait for the first.

What we recommend

1. Invert the sequencing. Make the dashboard critical path the first mediation domain. Scope it to the eight login fan-out APIs, extended to the experience map's 42, and prove the model there: mandatory token exchange, mandatory rate limiting against the FCC ceiling, a published latency budget, redaction on the aggregation path. A bounded slice that produces the operational evidence an enterprise rollout needs — and that lets the portal proceed without waiting on an enterprise programme.
2. Write the boundary rule, not the boundary. A capability belongs in the Inter layer when it is enterprise-uniform and its variation across LOBs would be a defect; in the Intra layer when variation is legitimate. Then apply it to the contested capabilities — orchestration, transformation, resiliency — and record the result. Without the rule, the boundary is relitigated per API.
3. Rule on orchestration explicitly, because the Integration API's future depends on it.
4. State the coexistence position per gateway, with a deprecation date or an explicit permanent exception for GB-APIM. "Centralized" that does not say what happens to a production gateway serving a third of the API surface is proposing a migration it has not costed.
5. Re-run the comparative study against the options the client's own later material frames. The architecture decision deck compares single BFF, federated GraphQL and CQRS over an event backbone. The mediation proposal's own current-state slide already names GraphQL-based APIs and event-driven architecture as things Manulife runs today. Those are the same decision at two altitudes, eighteen months apart, and nobody has put them on one page.

What we need to confirm it

CR-39 — whether the Inter layer replaces, fronts or renames PIE-APIM and GB-APIM, and any migration plan or funding position that exists.

---

Considerations that hold regardless

These are true whether or not anyone rules on anything, and the target state has to absorb them.

#	Consideration
1	The proposal is eighteen months old and nothing written since cites it. It predates the ADS, both client reviews and the June 2026 strategy. Its standing must be established before the target state depends on it.
2	Its co-author owns open question 8. The Chief Architect is the named owner of which statement of target state is the North Star of record. A proposal from that office, unreferenced by the four documents that followed it, is evidence for the "no agreed North Star" finding rather than against it.
3	Every capability the proposal adds is a capability someone must run. No operating model, on-call rotation or cross-BU arbitration forum exists for a shared enterprise runtime — finding F-04, and open question 14. A mediation layer adds a third component with no natural business-unit home.
4	MCP support is stated as intent, not design. Slide 7 positions the layer as future-proof with Model Context Protocol as the worked example. No protocol adapter, schema translation or tool-exposure mechanism is specified. Treat it as direction, not capability.
5	A mediation layer is the cheapest place to fix several findings at once — token exchange (B-01), enforced rate limits (D-03, L), redaction (G), distributed tracing across the ten-hop path (G). That is the argument for it, and it is stronger than the one the deck makes.

Where the content is being assembled

• Source summary: API Mediation proposal
• Positions this review produced — theme R4: R4.1, R4.2, R4.3
• Positions this review produced on the decisions the deck left open — theme R6: R6.2, R6.3
• Positions this review sharpens: R1.1, R2.1, R2.2, R2.4, R3.1
• Unresolved items: open questions 29–32, 36 and 37
• Evidence requested: CR-39 and CR-40
• Target-state home: D2.1 § Integration and API architecture, once written

Diagrams

Two would carry this review. Neither is authored yet.

• The mediated call path — one dashboard render across the Integration API, Inter layer, Intra layer and LOB service, with trust boundaries and the hop count visible. A sequence diagram, drawn to the same bar Domain K applies: protocol, authentication and data classification on every connector.
• Token exchange, before and after — the Area 2 worked example as a two-state comparison. This is the artifact that makes B-01 legible to a non-technical executive, and it is the single most useful diagram this engagement could produce.

Acceptance

This deliverable is outside Schedule "A", so it is not subject to the §5 acceptance cycle unless Manulife asks for it to be. Confirm with the client PM whether it is submitted as a standalone review or folded into D2.1 as the integration and API architecture section — tracked as open question 32.