Overview

This issue tracks the implementation of a customer sharing model for platform organizations and the refactoring of API key authentication to support platform-connected merchant operations.

Background

In a platform-connected merchant setup:

• Platform merchants can operate on behalf of connected merchants
• Connected merchants are sub-merchants under a platform organization
• Resources (customers, payment methods) need proper ownership and access control

Problems Addressed

1. Customer Duplication

• Previous: Each connected merchant owned their own customers
• Issue: When a customer transacted across multiple connected merchants, duplicate customer records were created
• Impact: Data inconsistency, poor customer experience

2. Authentication Layer Issues

• Previous: Duplicated validation logic across authentication functions
• Issue: Code was hard to maintain, inconsistent validation, early returns everywhere
• Impact: Technical debt, potential security gaps

3. Rigid Header Requirements

• Previous: Platform merchants MUST always send x-connected-merchant-id header
• Issue: Platform couldn't operate on their own shared resources without specifying a connected merchant
• Impact: Poor API ergonomics, unnecessary complexity

4. Partial-Auth Validation Gap

• Previous: HeaderAuth partial-auth flow bypassed merchant access validation
• Issue: Security vulnerability where merchant type restrictions weren't enforced
• Impact: Potential unauthorized access

Technical Details

Provider vs Processor Model

Provider: Platform merchant (owns resources)
Processor: Connected merchant or Platform (processes transactions)

Customer Operations → Use Provider (shared pool)
Transaction Operations → Use Processor (merchant-specific)

Migration Notes

API Contract Changes

• Customer endpoints now accept is_platform_allowed: true and is_connected_allowed: true
• x-connected-merchant-id header is optional for platform merchants
• No breaking changes to existing APIs

Backward Compatibility

• Existing standard merchants should remain unaffected
• Platform Merchant and Connected Merchants should be able to perform customers operations with a shared pool of data