Federation Endpoints

Federation is the relationship between a tenant instance (your shop) and the central marketplace (carphacom.com). Tenants read the catalog, download items, verify licenses. The marketplace only ever receives:

• Marketplace ID + version of items the tenant is interested in
• Encrypted instance ID for license verification
• No customer data, no order data, no product data

Tenant configuration

In the tenant's admin .env.local:

CARPHACOM_FEDERATION_URL=https://carphacom.com
CARPHACOM_FEDERATION_PK=pk_<central instance publishable key>

The tenant admin proxy uses these to call the central instance's /store/marketplace/* endpoints. Without these vars, the marketplace tab shows local plugins only.

Endpoints (called by tenants on carphacom.com)

GET /store/marketplace/feed

Headers: x-publishable-api-key: $CARPHACOM_FEDERATION_PK

Query: ?type=&search=&page=&per_page=

Returns paginated products with manifests:

{
  "products": [
    {
      "id": "ccmp_01...",
      "marketplace_id": "@carphacom/seo-essentials",
      "name": "SEO Essentials",
      "type": "admin-extension",
      "version": "1.0.0",
      "price_eur": 0,
      "manifest": { "id": "seo-essentials", ... },
      "download_url": "/store/marketplace/download/@carphacom/seo-essentials/1.0.0",
      "sha256": "...",
      "published_at": "..."
    }
  ],
  "count": 13, "limit": 20, "offset": 0
}

GET /store/marketplace/feed/{marketplaceId}

Single product with all versions and full description.

GET /store/marketplace/updates

curl 'https://carphacom.com/store/marketplace/updates?versions={"@carphacom/seo-essentials":"1.0.0"}' \
  -H "x-publishable-api-key: $CARPHACOM_FEDERATION_PK"

{ "updates": [{ "marketplace_id": "@v/p", "current": "1.0.0", "latest": "1.1.0", "changelog_url": "..." }] }

GET /store/marketplace/download/{marketplaceId}/{version}

{ "url": "https://cdn.carphacom.com/...?sig=...", "expires_at": "...", "sha256": "..." }

The signed URL is valid 15 minutes. The tenant downloads, verifies sha256 + signature, then installs.

POST /store/marketplace/checkout/session

For paid items:

{
  "marketplace_id": "@vendor/plugin",
  "version": "2.0.0",
  "customer_email": "merchant@shop.com",
  "instance_id": "inst_01..."
}

Returns Stripe Checkout URL. After payment, license is issued and a webhook fires to {tenant_instance}/admin/marketplace/license-issued containing the license key.

POST /store/marketplace/license/verify

See Webhooks & License Verify.

Webhooks (received by tenant from marketplace)

POST {tenant}/admin/marketplace/license-issued

Sent by carphacom.com after a purchase completes. Body:

{
  "marketplace_id": "@vendor/plugin",
  "version": "1.0.0",
  "license_key": "CC-...",
  "purchased_by": "merchant@shop.com"
}

The tenant verifies the request signature (X-Carpha-Signature), then auto-installs the purchased item.

Privacy & data isolation

The tenant never transmits to carphacom.com:

• Customer names, emails, addresses
• Order details, line items, prices paid
• Inventory levels, product details, sales numbers

Only marketplace IDs + versions + the tenant's encrypted instance ID are shared. Verify by inspecting outbound traffic: tcpdump -A 'host carphacom.com'.