REST API reference

The CloudGrange API is an ASP.NET Core Minimal API served by the cloudgrange-api container (port 8080 internally). In the on-premises preview, nginx proxies it through port 443 alongside the portal. Azure-hosted PaaS is not currently released.

All application endpoints are prefixed with /api/v1. The routes below are extracted from the endpoint definitions in cloudgrange-platform-api (src/CloudGrange.Api/Endpoints).

This surface reflects current preview code and may change during the preview. See current product and release status.

Authentication and authorization

All endpoints except the health probes and the setup endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <access_token>

The platform authenticates against Keycloak (local, on-premises) or Microsoft Entra ID (optional, Azure-hosted). POST /api/v1/auth/local-login issues a token for a local account (used by automation and the CLI). GET /api/v1/auth/me/permissions returns the caller's effective permissions — authorization is scope- and permission-checked per endpoint via the platform's RBAC.

Health probes

Unauthenticated, used by load balancers, orchestrators, and monitoring.

Route Description
GET /health/live Liveness — 200 if the API process is running.
GET /health/ready Readiness — 200 when dependencies (database, migrations) are ready.
GET /health/startup Startup — 200 once initialization completes.

Setup

Active only until first-run setup completes; afterwards they return an error.

Route Description
GET /api/v1/setup/status Current setup state.
POST /api/v1/setup Complete first-run setup (creates org + initial administrator).
POST /api/v1/auth/local-login Authenticate a local account; returns an access token.

Clusters and inventory

Route Description
GET /api/v1/clusters List clusters.
GET /api/v1/clusters/{id} Get a cluster.
POST /api/v1/clusters/{id}/nodes Add a node to a cluster.
GET /api/v1/clusters/{id}/nodes List a cluster's nodes.
GET /api/v1/clusters/{id}/health Cluster health.
GET /api/v1/vms List virtual machines.
GET /api/v1/vms/{id} Get a virtual machine.
GET /api/v1/workloads List workloads.
GET /api/v1/workloads/{id} Get a workload.

Jobs

Route Description
GET /api/v1/jobs/{jobId} Job status.
GET /api/v1/jobs/{jobId}/log Job log.
POST /api/v1/jobs/batch Submit a batch of jobs.
GET /api/v1/jobs/batch/{batchId} Batch status.
GET /api/v1/jobs/batch/{batchId}/items Batch items.

Modules and platform

Route Description
GET /api/v1/modules List installed modules.
POST /api/v1/modules/install Install a module.
DELETE /api/v1/modules/{key} Uninstall a module.
POST /api/v1/modules/{key}/enable Enable a module.
POST /api/v1/modules/{key}/disable Disable a module.
GET /api/v1/modules/{key}/permissions Module permissions.
GET /api/v1/modules/{key}/dependencies Module dependencies.
GET /api/v1/modules/{key}/health Module health.
GET /api/v1/modules/catalog Published module catalog.
POST /api/v1/modules/{id}/install Install a module from the catalog.
DELETE /api/v1/modules/{id} (catalog) Remove a catalog module.
GET /api/v1/platform/setup-status Platform setup status.
GET /api/v1/platform/health Platform health.
GET /api/v1/platform/version Platform version.

Platform updates

Route Description
GET /api/v1/platform/update/check Check for an available update.
GET /api/v1/platform/update/status Current update status.
POST /api/v1/platform/update/upload Upload an update package.
POST /api/v1/platform/update/apply Apply the update.
POST /api/v1/platform/update/rollback Roll back to the previous version.

Secrets

These routes currently manage secret-reference metadata, not secret values. Supported provider labels include local-encrypted, Key Vault, Keycloak, and manual, but the general PostgreSQL-encrypted value backend and real rotation pipeline are not complete. Identity-provider client secrets are separately encrypted with AES-256-GCM.

Route Description
GET /api/v1/secrets/refs List secret references.
GET /api/v1/secrets/refs/export Export references.
GET /api/v1/secrets/refs/{id} Get a reference.
POST /api/v1/secrets/refs Create a reference.
DELETE /api/v1/secrets/refs/{id} Delete a reference.
POST /api/v1/secrets/refs/{id}/rotate Preview placeholder: stamps rotation metadata; it does not rotate provider material yet.

Sites, relays, and agents

Route Description
GET /api/v1/platform/sites · POST · GET/PUT/DELETE /{id} Site management.
POST /api/v1/platform/sites/{id}/relay-token Mint a relay enrollment token for a site.
GET /api/v1/relays · GET/DELETE /{id} Relay registration and health.
POST /api/v1/relays/enroll-token · POST /api/v1/relays/enroll Relay enrollment.
POST /api/v1/relays/{id}/heartbeat Relay heartbeat.

Identity, users, and permissions

Route Description
GET /api/v1/identity/users · POST /api/v1/identity/users/invite User management.
GET /api/v1/roles List the organization's role catalog.
GET/POST /api/v1/identity/idp · PUT/DELETE /{id} · POST /{id}/test Identity provider configuration.
GET /api/v1/platform/identity · POST /consent-callback · GET/POST /providers Platform identity provider configuration.
GET /api/v1/auth/me/permissions Caller's effective permissions.

Configuration, notifications, and audit

Route Description
GET /api/v1/config/variables Variable registry definitions.
GET/PUT/DELETE /api/v1/config/values/{scopeId}/{key} Scoped configuration values.
GET /api/v1/config/snapshot/{scopeId} Configuration snapshot for a scope.
GET /api/v1/notifications · PATCH /{id}/read · POST /read-all Notifications.
GET /api/v1/audit · GET /export Audit log query/export.
GET /api/v1/capabilities Advertised platform capabilities.

Hardware catalog and drift

Route Description
GET/POST /api/v1/hardware-catalog/profiles · GET/DELETE /{id} Hardware profiles.
GET /api/v1/drift · GET /{id} · POST /{id}/acknowledge Hardware drift reports.

See current product and release status.