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'.