API Introduction

Base URLs, authentication, error format, and route groups for the Control Plane REST API.

The Control Plane exposes a REST API for programmatic access to accounts, workspaces, and all MVP pillars.

Base URLs

Environment	URL
Production	`https://platform.groundfloor.cloud`
Development	`https://dev-platform.groundfloor.cloud`
Local	`http://localhost:8088`

Route groups

Prefix	Audience	Description
`/v1/*`	Customer	Account-scoped customer endpoints
`/v1/admin/*`	Operator	Groundfloor staff endpoints
`/v1/public/*`	Unauthenticated	Bootstrap, routing, TLS authorization (rate-limited)

Authentication

All customer endpoints require a Bearer JWT from Keycloak:

curl -H "Authorization: Bearer $TOKEN" \
  "$CP_URL/v1/workspaces"

The JWT sub claim maps to a Portal user. SpiceDB checks permissions per request.

Error format

{
  "detail": "Human-readable message",
  "code": "machine_readable_code"
}

Status	Meaning
401	Missing or expired JWT
403	SpiceDB denied the action
404	Resource not found or no read permission
422	Validation error

Workspace-scoped endpoints

Most pillar APIs are scoped under a workspace:

/v1/workspaces/{workspace_id}/vault/…
/v1/workspaces/{workspace_id}/files/…
/v1/workspaces/{workspace_id}/secrets/…

Full per-endpoint reference pages are available for authentication, accounts, workspaces, memberships, secrets, files, and data vault. For Shell apps, see the Shell API reference.

Documentation index

Guide	Topics
Authentication	JWT, permissions, public routes
Accounts	List, create, audit, quota
Workspaces	CRUD, environments, export
Memberships	Scope members, roles, revoke
Data Vault	Collections, query, DDL
Files	Presigned upload/download
Secrets	List, reveal, upsert, delete

OpenAPI

FastAPI serves an OpenAPI spec at /openapi.json. Auto-generated interactive docs are planned for a future release.