MCM-08 — MCM Instance Subscription Validation

← Back to MCM Nexus overview

As an MCM App User (deployed MCM instance),
I want to authenticate to Nexus and check my organization's subscription status,
so that the instance can confirm it is entitled to run before enabling itself for its users.

Acceptance Criteria

• The customer enters the MCM App username and password into their deployed MCM instance's configuration once, after which the instance authenticates to Nexus itself — no further manual steps.
• Nexus exposes an instance-facing endpoint, authenticated as the MCM App User, returning license status (ACTIVE / DEACTIVATED / EXPIRED / NOT_ACTIVATED), the validity window, and the role/plan the instance is entitled to run as.
• The instance polls this endpoint every 24 hours (not on every request) and caches the last good result; a single failed poll (network blip, Nexus briefly unreachable) does not invalidate the cached status — only repeated failures or an explicit DEACTIVATED/EXPIRED response do.
• Once the cached status is DEACTIVATED/EXPIRED and the user is on the resulting blocked screen (see MCM-32), a manual "Check Again" action calls this same endpoint on demand, bypassing the 24-hour schedule — so a customer who just renewed isn't stuck waiting up to 24 hours for the next scheduled poll to notice.
• The endpoint responds quickly enough to be polled safely at the expected interval and is rate-limited / abuse-protected, since it is reachable from wherever a customer instance is deployed, not just from internal traffic.
• Every validation call is audit-logged (organization, timestamp, source IP) so the Nexus Admin can spot irregular patterns (e.g. the same MCM App credential validating from many different IPs) and so support can debug a customer-reported connectivity issue.
• Each poll also reports the instance's currently-installed MCM version, so Nexus always has an up-to-date record of what every Organization is actually running — the Nexus Admin and the customer can both see this (see MCM-12 — Nexus Admin Operational Visibility and MCM-09 — Download MCM Installation Package) without needing a separate check-in mechanism.

---

Technical Design

Adds a new instance-facing endpoint, GET /api/mcm-app/subscription/status, to mcm-nexus/backend, authenticated as the MCM_APP Keycloak principal for the calling Organization — a capability Nexus explicitly deferred before this story ("record status only, no instance-facing API"). Every call updates MCM App Credential.lastValidatedAt and writes an audit log entry (organization, timestamp, source IP), and the endpoint is rate-limited since it is reachable from wherever a customer instance is deployed. The instance polls on a 24-hour schedule and caches the last good result; only repeated failures or an explicit DEACTIVATED/EXPIRED response invalidate a working instance, not a single network blip. The same endpoint also backs an on-demand call from the blocked-access screen's "Check Again" action (see MCM-32) — identical request, just triggered by the user instead of the schedule, so a renewal is reflected immediately rather than on the next scheduled poll. The poll request now also carries the instance's currently-installed version as a query parameter, stored as MCM App Credential.installedVersion alongside lastValidatedAt — reusing this existing periodic call rather than adding a second reporting channel.

---

UI / Frontend Changes

• This story is primarily instance-to-Nexus API traffic with no direct customer-facing screen of its own, but it feeds the Nexus Admin console: last-validated timestamp and currently-installed version per organization (surfaced on (admin)/admin/customers, see Subscription Activation and Secure Credential Delivery and MCM-12 — Nexus Admin Operational Visibility), and the customer's own (customer)/license page (see MCM-09).
• Deployed MCM instance's own UI reflects the cached subscription state (e.g. a banner if the license is DEACTIVATED/EXPIRED) — that instance-side UI lives outside mcm-nexus but consumes this endpoint's response; see MCM-32 — MSP Access Restriction on Subscription Expiry for the full enforcement/banner/extend-plan behavior.
• No new Nexus portal screen is introduced by this story; it is consumed machine-to-machine by the deployed instance.