KubeDB Platform API Reference

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.

A machine-readable OpenAPI 3.0.3 specification 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, interactive Swagger UI viewer (with the spec inlined) is also published for this release — open it to browse and try every endpoint in the browser.

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

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:

Authorization: token <YOUR_TOKEN>

You can also pass it as a token or access_token query parameter. Token-management 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.

The server supports several authentication mechanisms:

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:

Typical Request Flows

Cluster resource access via the Kubernetes proxy

License issuance for a contract cluster

Usage → billing pipeline

Deployment Modes

Feature gating summary:

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