appscode-cloud · tamalsaha · Jul 14, 2026 · Jul 14, 2026 · Jul 14, 2026
diff --git a/docs/platform/api/README.md b/docs/platform/api/README.md
@@ -11,18 +11,56 @@ section_menu_id: api
 url: /docs/platform/{{.version}}/api/
 aliases:
 - /docs/platform/{{.version}}/api/README/
+- /docs/platform/{{.version}}/api/overview/
 ---
 
 # KubeDB Platform API Reference
 
-Low-level reference for the KubeDB Platform API. Every endpoint lists its HTTP method, path, authentication, path/query
-parameters, and request/response shapes so you can implement a client directly
-against it.
+The **KubeDB Platform API Server** is the backend server of the KubeDB Platform. This page gives you both
+the whole-system picture — what the server does, how it is put together, how
+requests are authenticated and authorized, and how the pieces fit into typical
+flows — and the entry point to the low-level, endpoint-by-endpoint reference. Every
+endpoint on the per-group pages lists its HTTP method, path, authentication,
+path/query parameters, and request/response shapes so you can implement a client
+directly against it.
 
 All routes are served under the `/api/v1` prefix unless noted otherwise. The
 marketplace webhook service is a separate listener rooted at `/marketplace/api/v1`.
 
-## Authentication
+A machine-readable [OpenAPI 3.0.3 specification](../api/openapi.yaml) of this API is
+also available (`openapi.yaml`) — load it into any OpenAPI tool (Swagger UI, Redoc,
+`openapi-generator`) to explore the API or generate a client. A self-contained
+Swagger UI viewer (`api.html`, with the spec inlined) is available at the repository
+root.
+
+## Overview
+
+The KubeDB Platform API Server combines an identity foundation (users, organizations, teams,
+authentication) with a multi-cluster Kubernetes management platform providing:
+
+- **Identity & access management** — users, organizations, teams, fine-grained authorization.
+- **Cluster management** — import, provision, and operate Kubernetes clusters (hub/spoke via Open Cluster Management, Rancher, cloud providers).
+- **A full Kubernetes API proxy** — the KubeDB Platform UI talks to member clusters through the KubeDB Platform API Server.
+- **Licensing & contracts** — issuing and enforcing product licenses (KubeDB, KubeStash, KubeVault, Voyager, ...).
+- **Billing & usage reporting** — usage aggregation, invoices, cloud-marketplace metering (AWS/Azure/GCP).
+- **Monitoring & telemetry** — telemetry stack provisioning, Prometheus/Trickster auth proxying.
+
+## System Architecture
+
+![KubeDB Platform system architecture](../api/images/architecture.svg)
+
+Key runtime facts:
+
+- One binary, multiple subcommands. The default command is the API server; `marketplace`, `monitor`,
+  `aggregator`, and `summary` run as separate processes for async/billing workloads.
+- **NATS/JetStream** is the event backbone: member clusters push resource/usage events; `monitor` and
+  `aggregator` consume them; the API server also uses NATS for its task manager and per-user credentials.
+- **FluxCD (HelmRelease)** and **OCM (ManagedCluster)** are used to deploy KubeDB Platform features onto clusters and
+  to manage hub→spoke relationships.
+- Deployment modes are switched by `DEPLOYMENT_TYPE`: AppsCode-hosted, self-hosted (incl. offline
+  installer), or AWS/GCP marketplace deployments. Some API groups only exist in specific modes (noted below).
+
+## Authentication & Authorization
 
 Most endpoints require a personal access token. Send it as an HTTP header:
 
@@ -35,31 +73,85 @@ endpoints accept HTTP Basic auth. The web console uses a session cookie
 (`i_like_ace`); a session cookie alone does **not** authenticate the token-guarded
 REST endpoints — use a token.
 
-A machine-readable [OpenAPI 3.0.3 specification](../api/openapi.yaml) of this API is
-also available (`openapi.yaml`) — load it into any OpenAPI tool (Swagger UI, Redoc,
-`openapi-generator`) to explore the API or generate a client. A self-contained
-Swagger UI viewer (`api.html`, with the spec inlined) is available at the repository
-root.
+The server supports several authentication mechanisms:
+
+| Mechanism | Used by | Notes |
+|---|---|---|
+| Session cookie | Web console | Cookie-based sign-in; CSRF-protected |
+| Personal access token / Bearer token | API clients, CLI | `Authorization: token <t>`, `?token=`, `?access_token=` |
+| Basic auth | Token management endpoints | With optional OTP (2FA) |
+| OAuth2 / OIDC | SSO; the KubeDB Platform API Server is both provider and consumer | `/login/oauth/*`, `/.well-known/openid-configuration` |
+| LDAP / PAM | Enterprise sign-in sources | Configured by site admins |
+| 2FA / WebAuthn | User accounts | TOTP, scratch tokens, security keys |
+| License-based auth | Member clusters | Clusters authenticate with issued licenses / cluster tokens |
+| Sudo | Site admins | Impersonate a user via `sudo` param/header |
+
+Authorization is relationship-based (OpenFGA-style checks, shown as `authzCheck(<permission>)` in the
+reference tables). Common middleware referenced in the API tables:
+
+- **Token** — authenticated request required (`reqToken`).
+- **Site admin** — platform administrator only.
+- **Org context** — org resolved from path or `?org=` query; membership/ownership verified.
+- **Cluster assignment** — resolves owner+cluster, loads cluster credentials, builds a Kubernetes client.
+- **Public** — no authentication beyond baseline middleware.
+
+Baseline middleware on every `/api/v1` route: optional-sign-in, NATS connection cleanup,
+security headers (`nosniff`), API context, sudo support.
+
+## API Groups
+
+The v1 API surface is organized into the following logical groups:
+
+| # | Group | Base path(s) | What it covers | Availability |
+|---|-------|--------------|----------------|--------------|
+| 1 | [Identity: Users & Settings](../api/users-settings/) | `/api/v1/user`, `/api/v1/users` | Accounts, profile/security settings, tokens, credentials | always |
+| 2 | [Identity: Organizations & Teams](../api/organizations-teams/) | `/api/v1/orgs`, `/api/v1/teams` | Orgs, members, teams, org tokens | always |
+| 3 | [Administration](../api/administration/) | `/api/v1/admin`, `/api/v1/accounts/admin` | Admin console, site settings | always |
+| 4 | [Authorization (Roles & Permissions)](../api/authorization/) | `/api/v1/authz` | Custom roles & permissions | always |
+| 5 | [Cluster Management (v1 + K8s proxy + Helm)](../api/cluster-management-v1/) | `/api/v1/clusters` | Cluster lifecycle, Kubernetes proxy, Helm | always |
+| 6 | [Cluster Management v2](../api/cluster-management-v2/) | `/api/v1/clustersv2` | Hub-aware cluster API, subscriptions, gateways | always |
+| 7 | [Multi-cluster (OCM hub/spoke)](../api/multicluster-ocm/) | `/api/v1/clusters/:owner/:cluster/...` | Hub/spoke, cluster sets, feature sets | always |
+| 8 | [Client Organizations](../api/client-organizations/) | `/api/v1/user/client*`, `/api/v1/clusters/.../permission` | Managed-service client orgs | always |
+| 9 | [Cloud Providers](../api/cloud-providers/) | `/api/v1/clouds` | Provider discovery for provisioning | always |
+| 10 | [Platform Installer](../api/ace-installer/) | `/api/v1/ace-installer` | Self-host installer bundles | AppsCode-hosted only |
+| 11 | [Platform Upgrade](../api/ace-upgrade/) | `/api/v1/upgrade`, `/api/v1/clusters/.../upgrade` | Platform & cluster upgrades | always |
+| 12 | [Licensing & Contracts](../api/licensing-contracts/) | `/api/v1/contracts`, `/api/v1/user/contracts`, `/api/v1/register`, `/api/v1/license` | Contracts, licenses, registration | contracts: AppsCode-hosted |
+| 13 | [Billing Dashboard & Usage Reports](../api/billing-dashboard/) | `/api/v1/dashboard`, `/api/v1/user/dashboard`, `/api/v1/dbaas` | Usage reports & billing dashboards | billing-enabled deployments |
+| 14 | [Marketplace](../api/marketplace/) | `/api/v1/marketplaces` (separate service), `/api/v1/proxy/metered-billing` | Cloud-marketplace webhooks & metering | marketplace deployments |
+| 15 | [Monitoring & Telemetry](../api/monitoring-telemetry/) | `/api/v1/telemetry`, `/api/v1/trickster` | Telemetry stack, Trickster auth proxy | always |
+| 16 | [Rancher Integration](../api/rancher/) | `/api/v1/rancher` | Rancher sync & proxy | always |
+| 17 | [Helm Chart Repositories (public)](../api/chart-repositories/) | `/api/v1/chartrepositories` | Public Helm chart repositories | always |
+| 18 | [Miscellaneous & Site Settings](../api/miscellaneous/) | `/api/v1/version`, `/api/v1/markdown`, `/api/v1/branding`, ... | Version, markdown, health | always |
+
+![KubeDB Platform /api/v1 API group map](../api/images/api-groups.svg)
+
+## Typical Request Flows
+
+### Cluster resource access via the Kubernetes proxy
+
+![Kubernetes proxy request flow](../api/images/flow-proxy.svg)
+
+### License issuance for a contract cluster
+
+![License issuance flow](../api/images/flow-license.svg)
+
+### Usage → billing pipeline
+
+![Usage to billing pipeline](../api/images/flow-billing.svg)
+
+## Deployment Modes
+
+| Mode | `DEPLOYMENT_TYPE` | Notes |
+|---|---|---|
+| AppsCode-hosted (SaaS) | `Hosted` | Full surface incl. contracts admin, installer, Firebase tokens |
+| Self-hosted | `SelfHostedProduction` (offline installs also set the separate `OfflineInstaller` flag) | Runs from a generated installer bundle; `/selfhost` console URL |
+| AWS Marketplace | `AWSMarketplace` | Marketplace webhooks + AWS metering proxy enabled |
+| GCP Marketplace | `GoogleCloudMarketplace` | Marketplace webhooks + GCP metering proxy enabled |
+| Azure Marketplace | `AzureMarketplace` | Recognized marketplace mode (webhooks); no metering proxy wired up |
+
+Feature gating summary:
 
-## API groups
-
-| Group | What it covers |
-|---|---|
-| [Identity: Users & Settings](../api/users-settings/public-user-apis/) | Accounts, profile/security settings, tokens, credentials |
-| [Identity: Organizations & Teams](../api/organizations-teams/organizations/) | Orgs, members, teams, org tokens |
-| [Administration](../api/administration/admin-org/) | Admin console, site settings |
-| [Authorization](../api/authorization/roles-permissions/) | Custom roles & permissions |
-| [Cluster Management v1](../api/cluster-management-v1/lifecycle/) | Cluster lifecycle, Kubernetes proxy, Helm |
-| [Cluster Management v2](../api/cluster-management-v2/clusters/) | Hub-aware cluster API, subscriptions, gateways |
-| [Multi-cluster (OCM)](../api/multicluster-ocm/hubs-spokes/) | Hub/spoke, cluster sets, feature sets |
-| [Client Organizations](../api/client-organizations/management/) | Managed-service client orgs |
-| [Cloud Providers](../api/cloud-providers/cloud-providers/) | Provider discovery for provisioning |
-| [Platform Installer](../api/ace-installer/ace-installer/) | Self-host installer bundles |
-| [Platform Upgrade](../api/ace-upgrade/platform-upgrade/) | Platform & cluster upgrades |
-| [Licensing & Contracts](../api/licensing-contracts/registration/) | Contracts, licenses, registration |
-| [Billing Dashboard](../api/billing-dashboard/admin-dashboard/) | Usage reports & billing dashboards |
-| [Marketplace](../api/marketplace/webhook-service/) | Cloud-marketplace webhooks & metering |
-| [Monitoring & Telemetry](../api/monitoring-telemetry/telemetry-stack/) | Telemetry stack, Trickster auth proxy |
-| [Rancher Integration](../api/rancher/rancher/) | Rancher sync & proxy |
-| [Chart Repositories](../api/chart-repositories/chart-repositories/) | Public Helm chart repositories |
-| [Miscellaneous](../api/miscellaneous/miscellaneous/) | Version, markdown, health |
+- `AppsCodeHosted` → contracts admin APIs, installer APIs, org claim, Firebase token.
+- `IsBillingEnabled()` → billing dashboard APIs (admin, user, usage reports).
+- `DeploymentType` → which marketplace metering proxy (if any) is registered.
+- License enforcement is compiled in (`ENFORCE_LICENSE=true`); the server validates its own license at startup.
diff --git a/docs/platform/api/ace-installer/README.md b/docs/platform/api/ace-installer/README.md
@@ -0,0 +1,53 @@
+---
+layout: docs
+menu:
+  docsplatform_{{.version}}:
+    identifier: api-ace-installer-readme
+    name: Overview
+    parent: api-ace-installer
+    weight: 1
+menu_name: docsplatform_{{.version}}
+section_menu_id: api
+url: /docs/platform/{{.version}}/api/ace-installer/
+aliases:
+- /docs/platform/{{.version}}/api/ace-installer/overview/
+---
+
+# Platform Installer API
+
+The Platform Installer API generates and manages self-host installer bundles for the
+KubeDB Platform. It serves the installer options schema,
+generates and imports installer bundles, lists and inspects generated installers,
+and supports reconfigure/upgrade/versioning and marketplace-installer status.
+
+> **AppsCode-hosted only.** Every route under `/api/v1/ace-installer/...` is available
+> only on the AppsCode-hosted (SaaS) deployment. On self-hosted KubeDB Platform installations these
+> routes are not registered and return `404 Not Found`. All calls require a bearer token,
+> an org context (resolved from the `org` query param), and per-action authorization
+> checks (`view_installers`, `create_installers`, `import_installers`,
+> `reconfigure_installers`, `upgrade_installers`, `download_installers`,
+> `delete_installers`).
+
+`/api/v1/ace-installer` (AppsCode-hosted only)
+
+Generates and manages self-host installer bundles. Token + org context; per-action authz checks.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/schema.json`, `/model.json` | Installer JSON schema / default options |
+| POST | `/generate` | Generate an installer |
+| POST | `/import` | Import an installer |
+| GET | `/installer-meta`, `/latest-version` | Installer metadata / latest KubeDB Platform version |
+| GET | `/installers/` (+`/:name/`, `/:name/:id`) | List / inspect installers |
+| DELETE | `/installers/:name/:id` | Delete a generated installer |
+| POST | `/installers/:name/:id/{reconfigure,upgrade}` | Reconfigure / upgrade an installer |
+| GET | `/installers/:name/:id/versions` | List installer versions |
+| GET | `/installers/:name/:id/archives/:archiveName` | Read installer archive details |
+| GET | `/installers/:name/:id/model.json` | Installer options |
+| GET | `/deployment/marketplace/installers/:installerID/status` | Marketplace installer status |
+
+## Pages
+
+- [Platform Installer](../ace-installer.md) — schema/model, generate/import,
+  installer metadata and latest version, installers CRUD, reconfigure/upgrade,
+  versions/archives, and marketplace installer status.
diff --git a/docs/platform/api/ace-installer/_index.md b/docs/platform/api/ace-installer/_index.md
@@ -9,24 +9,3 @@ menu:
 menu_name: docsplatform_{{.version}}
 section_menu_id: api
 ---
-
-# Platform Installer API
-
-The Platform Installer API generates and manages self-host installer bundles for the
-KubeDB Platform. It serves the installer options schema,
-generates and imports installer bundles, lists and inspects generated installers,
-and supports reconfigure/upgrade/versioning and marketplace-installer status.
-
-> **AppsCode-hosted only.** Every route under `/api/v1/ace-installer/...` is available
-> only on the AppsCode-hosted (SaaS) deployment. On self-hosted KubeDB Platform installations these
-> routes are not registered and return `404 Not Found`. All calls require a bearer token,
-> an org context (resolved from the `org` query param), and per-action authorization
-> checks (`view_installers`, `create_installers`, `import_installers`,
-> `reconfigure_installers`, `upgrade_installers`, `download_installers`,
-> `delete_installers`).
-
-## Pages
-
-- [Platform Installer](../ace-installer.md) — schema/model, generate/import,
-  installer metadata and latest version, installers CRUD, reconfigure/upgrade,
-  versions/archives, and marketplace installer status.
diff --git a/docs/platform/api/ace-installer/overview.md b/docs/platform/api/ace-installer/overview.md
diff --git a/docs/platform/api/ace-upgrade/README.md b/docs/platform/api/ace-upgrade/README.md
@@ -0,0 +1,59 @@
+---
+layout: docs
+menu:
+  docsplatform_{{.version}}:
+    identifier: api-ace-upgrade-readme
+    name: Overview
+    parent: api-ace-upgrade
+    weight: 1
+menu_name: docsplatform_{{.version}}
+section_menu_id: api
+url: /docs/platform/{{.version}}/api/ace-upgrade/
+aliases:
+- /docs/platform/{{.version}}/api/ace-upgrade/overview/
+---
+
+# Platform Upgrade
+
+APIs for upgrading the KubeDB Platform itself and for upgrading the KubeDB Platform feature
+stack running inside imported and spoke clusters. Upgrades are FluxCD/Helm-driven
+and run asynchronously; progress and history are tracked in upgrader `ConfigMap`
+data, which these endpoints surface as dynamic key/value maps.
+
+All routes are served under the `/api/v1` prefix. Every endpoint authenticates
+with a personal access token sent as `Authorization: token <YOUR_TOKEN>` (it may
+also be supplied as a `token` or `access_token` query parameter).
+
+There are two distinct authorization models, which is why the endpoints are split
+across two pages:
+
+- **Platform upgrade** routes (`/api/v1/upgrade*`) act on the KubeDB Platform as a
+  whole. They require an organization context (`?org=<slug>`) and **site-admin
+  organization authorization** — `view_upgrade_history:org` for the read routes
+  and `upgrade_platform:org` for the trigger route.
+- **Cluster upgrade** routes (`/api/v1/clusters/{owner}/{cluster}/upgrade*` and
+  `.../spoke/upgrade*`) act on a specific member cluster and are gated by
+  **cluster assignment** for the given owner/cluster (plus a runtime client to
+  that cluster).
+
+Platform and per-cluster upgrades (FluxCD-driven).
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET/POST | `/api/v1/upgrade` | Token + org; site-admin authz (view_upgrade_history / upgrade_platform) | Platform upgrade status / trigger |
+| GET | `/api/v1/upgrade/{status,history,current-version}` | Token + org; site-admin authz (view_upgrade_history) | Upgrade job status, history, current version |
+| GET/POST | `/api/v1/clusters/:owner/:cluster/upgrade` | Cluster assignment + runtime client | Imported-cluster upgrade status / trigger |
+| GET | `/api/v1/clusters/:owner/:cluster/upgrade/{history,current-version,latest-version}` | Cluster assignment + runtime client | Upgrade info |
+| GET/POST | `/api/v1/clusters/:owner/:cluster/spoke/upgrade` (+`/history`) | Cluster assignment + runtime client | Spoke-cluster upgrade status / trigger / history |
+
+## Pages
+
+- [Platform Upgrade](../platform-upgrade.md) — the
+  `/api/v1/upgrade*` endpoints: platform upgrade status, job status, history, and
+  current version, plus triggering a platform upgrade. Requires site-admin org
+  authorization.
+- [Cluster Upgrade](../cluster-upgrade.md) — the
+  `/api/v1/clusters/{owner}/{cluster}/upgrade*` and `.../spoke/upgrade*`
+  endpoints: imported-cluster and spoke-cluster upgrade status, history, current
+  and latest versions, plus triggering cluster/spoke upgrades. Gated by cluster
+  assignment.