M2M Integration

Cloud and Management communicate in both directions using two distinct authentication mechanisms.

Communication channels

Direction	Endpoint	Auth	Purpose
Management → Cloud	POST /internal/license/refresh	HMAC-SHA256 signature	Push license activation
Cloud → Management	GET /internal/v1/*	X-Internal-Token header	Fetch license state

Shared secrets

Both secrets must have the same value in both services:

Secret	Env var	Purpose
Internal API token	CLOUD_INTERNAL_API_TOKEN	Bearer token for Cloud → Management calls
HMAC secret	CLOUD_WEBHOOK_HMAC_SECRET	Signing key for Management → Cloud webhook

Generate both with:

openssl rand -hex 32

Store the same values in both kv-mz-cloud-* and kv-mz-manage-* Azure Key Vaults.

Management → Cloud (HMAC webhook)

When Management activates a tenant license, it calls Cloud Backend with an HMAC-signed request:

POST {CLOUD_API_URL}/internal/license/refresh
X-Hmac-Signature: sha256=<hex_signature>
Content-Type: application/json

{ "tenant_id": "...", "plan": "...", "features": [...], "expires_at": "..." }

Signature verification (Cloud Backend):

1. Compute HMAC-SHA256(body, CLOUD_WEBHOOK_HMAC_SECRET)
2. Compare with X-Hmac-Signature header value (constant-time comparison)
3. Reject with 401 if mismatch

CLOUD_API_URL on Management must point to the Cloud Backend origin. In production, this is typically the Azure App Service URL (not the Cloudflare public URL) since Management may be on the same Azure network.

Cloud → Management (Bearer token)

Cloud Backend may call Management to fetch the current license state:

GET {MANAGEMENT_API_URL}/internal/v1/tenants/{cloud_tenant_id}/license
X-Internal-Token: {CLOUD_INTERNAL_API_TOKEN}

Management validates the X-Internal-Token header against its CLOUD_INTERNAL_API_TOKEN env var.

URL configuration

Env var	Set on	Example
CLOUD_API_URL	Management Backend	https://api.cloud.monozu.io
MANAGEMENT_API_URL	Cloud Backend	https://manage.monozu.io (App Service URL)

In local dev, use http://localhost:8000 and http://localhost:8080 respectively.

Networking note

In production, CLOUD_API_URL on Management should point to the Cloud App Service directly (e.g. https://app-monozu-cloud.azurewebsites.net), not through the Cloudflare proxy. This allows Management outbound IPs to be added to Cloud’s App Service access restrictions, preventing unauthorized webhook calls.