Skip to main content
All notable changes to the k0rdent API documentation will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

​
[Unreleased] - 2024-02-13

​
Changed - API Spec Restructure

Complete rewrite of OpenAPI specifications to align with MVP requirements from the k0rdent API Spec Google Sheet. This represents a major restructuring of the API surface to match the enterprise platform’s MVP scope. All changes are based on the Google Sheet defining 48 unique endpoints across 11 API domains as the source of truth.

​
Breaking Changes

  • Path prefix: All paths migrated from singular /v1/region/ to plural /v1/regions/
  • Arc API → Compute API: Restructured with focus on clusters, VMs, and SDN (14 endpoint groups)
  • Atlas API → Infrastructure API: Restructured for bare-metal server lifecycle and inventory (8 endpoint groups)
  • Auth API → Auth + IAM API: Consolidated authentication and identity/access management (10 endpoint groups)
  • Organizations extracted: Org/project management moved from individual specs to dedicated organizations spec

​
API Domain Changes

Compute API (formerly Arc)
  • 14 endpoint groups: clusters, VMs, networks, subnets, addresses, load balancers, peering, interconnects, firewalls
  • All paths: /v1/regions/{region}/compute/*
  • Removed: Organization/project paths (moved to organizations spec), storage endpoints, nested network sub-paths
  • New endpoints:
    • /v1/regions/{region}/compute/vms - Virtual machine lifecycle
    • /v1/regions/{region}/compute/subnets - Network IP mapping
    • /v1/regions/{region}/compute/addresses - IPAM: IP address allocations
    • /v1/regions/{region}/compute/loadbalancers - Network load balancing
    • /v1/regions/{region}/compute/peering - Within-region routing
    • /v1/regions/{region}/compute/interconnects - Region-to-region routing
    • /v1/regions/{region}/compute/firewalls - Network policy
    • /v1/regions/{region}/compute/clusters/{clusterId}/kubeconfigs - Kubeconfig issuance
    • /v1/regions/{region}/compute/clusters/{clusterId}/nodes/{nodeId}/ssh - Node SSH access
Infrastructure API (formerly Atlas)
  • 8 endpoint groups: servers CRUD, batch enrollment, batch/single actions, logs, profiles, switches
  • All paths: /v1/regions/{region}/infrastructure/*
  • Removed: Organization/project/quota paths, compute paths, storage paths
  • New endpoints:
    • /v1/regions/{region}/infrastructure/servers/batch - Bulk server enrollment (POST with array)
    • /v1/regions/{region}/infrastructure/servers/actions - Batch actions on multiple servers (POST with {action, ids})
    • /v1/regions/{region}/infrastructure/servers/{id}/actions - Single server actions (provision, validate, state transitions)
    • /v1/regions/{region}/infrastructure/servers/{id}/logs - Host provisioning & status logs
    • /v1/regions/{region}/infrastructure/profiles - Profiles/Persona CRUD
    • /v1/regions/{region}/infrastructure/switches - Network management
Auth + IAM API (formerly Auth)
  • 10 endpoint groups: tokens, sessions, users, user profiles, roles, groups, policies, service accounts, API keys, identity providers
  • All paths: /v1/regions/global/auth/* and /v1/regions/global/iam/*
  • Removed: Old auth paths (me, signup, invitations, organizations, members)
  • New endpoints:
    • /v1/regions/global/auth/tokens - OAuth2/OIDC token acquire/refresh/revoke
    • /v1/regions/global/auth/sessions - Session login/logout, list active sessions, MFA
    • /v1/regions/global/iam/users - Tenant user lifecycle
    • /v1/regions/global/iam/users/profile - Self-service profile
    • /v1/regions/global/iam/roles - Authorization/RBAC role definitions
    • /v1/regions/global/iam/groups - Group management (SSO-driven, IAM policy bindings)
    • /v1/regions/global/iam/policies - Role bindings at org/project/resource level
    • /v1/regions/global/iam/service-accounts - Machine identity for automation
    • /v1/regions/global/iam/apikeys - API key lifecycle management
    • /v1/regions/global/iam/providers - Identity provider configuration (SSO)
Organizations API (new)
  • 6 endpoint groups: organizations CRUD, org invitations, org quotas, folders (stub), projects, project quotas
  • All paths: /v1/regions/global/organizations/* and /v1/regions/global/projects/*
  • New spec consolidating org/project management previously scattered across arc, atlas, auth
  • Key decision: Projects are top-level at /v1/regions/global/projects (org context from auth token, not URL nesting)
  • Endpoints:
    • /v1/regions/global/organizations - Organization CRUD
    • /v1/regions/global/organizations/{orgId}/invitations - Organization invitations
    • /v1/regions/global/organizations/quotas - Customer org quota management
    • /v1/regions/global/organizations/folders - Folder management (stub — hierarchy TBD)
    • /v1/regions/global/projects - Top-level project management
    • /v1/regions/global/projects/quotas - Project quota management
Webhooks API (new)
  • 3 endpoint groups: webhooks, subscriptions, delivery history
  • All paths: /v1/regions/global/webhooks/*
  • Endpoints:
    • /v1/regions/global/webhooks - Webhook management
    • /v1/regions/global/webhooks/subscriptions - Webhook subscriptions
    • /v1/regions/global/webhooks/subscriptions/{id}/deliveries - Delivery history
Workflows API (new, internal-only)
  • 4 endpoint groups: workflow definitions, workflow runs, run logs, metrics
  • All paths: /v1/regions/global/workflows/*
  • Marked as internal-only — for platform orchestration, not public API
  • Endpoints:
    • /v1/regions/global/workflows - Workflow definitions/orchestration
    • /v1/regions/global/workflows/{id}/runs - Workflow execution instances
    • /v1/regions/global/workflows/{id}/runs/{runId}/logs - Workflow run logs
    • /v1/regions/global/workflows/metrics - Aggregate performance stats
Observability API (new, stub)
  • 1 endpoint: stub for future analytics & observability
  • Path: /v1/regions/global/observability
Audit API (simplified)
  • Path changed from /v1/region/{region}/audit/events to /v1/regions/global/audit
  • Single collection endpoint per spreadsheet spec
Billing API (simplified)
  • Path changed from /v1/region/global/billing/accounts/... to /v1/regions/global/projects/billing
  • Single endpoint per spreadsheet spec
Regions API (renamed)
  • Path changed from /v1/region/global/regions to /v1/regions/global/locations
Notifications API (prefix update)
  • Prefix updated from /v1/region/global/ to /v1/regions/global/
  • Existing endpoint structure preserved

​
Schema Changes

Common Schemas (added)
  • Quota - Resource quota configuration with enforcement policies (hard/soft)
  • Folder - Project organization hierarchy (stub — full design TBD)
Compute Schemas (new)
  • VM - Virtual machine definition
  • Subnet - Network subnet configuration
  • Address - IPAM IP address allocation
  • LoadBalancer - Load balancer configuration
  • PeeringConnection - Within-region network routing
  • Interconnect - Region-to-region network routing
  • Firewall - Network policy rules
Infrastructure Schemas (new)
  • Profile - Server profile/persona definition
  • Switch - Network switch management
  • ServerAction - Action enum: provision, validate, start, stop, restart, decommission
Auth + IAM Schemas (new)
  • Token - OAuth2/OIDC token
  • Session - User session
  • User - Tenant user
  • Role - RBAC role definition
  • Group - User group
  • Policy - IAM policy (role bindings)
  • ServiceAccount - Machine identity
  • ApiKey - API key credential
  • IdentityProvider - SSO provider configuration
Organizations Schemas
  • Organization, Project, Member, Invitation - Moved to organizations spec (previously scattered)
  • Folder - Stub for project hierarchy
  • Quota - Resource quota (shared schema)

​
Key Design Decisions

  1. Path naming: Plural /v1/regions/ per Google Sheet (singular was incorrect)
  2. Project URLs: Flat top-level /v1/regions/global/projects (org context from auth token, not URL nesting) — cleaner, less cluttered
  3. IAM consolidation: IAM endpoints folded into auth spec (single identity domain)
  4. Workflows visibility: Internal-only (still documented for platform developers)
  5. Instance types: Dropped for MVP (not in spreadsheet)
  6. Infrastructure actions: Both single (/servers/{id}/actions) and batch (/servers/actions) endpoints for flexibility
  7. Batch enrollment: Dedicated /servers/batch endpoint (POST array of servers)
  8. Folders: Stub only (GCP-style hierarchy design TBD)
  9. VMs vs Instances: Use /compute/vms terminology (not /compute/instances)

​
Files Changed

Source specs edited (7):
  • content/docs/api-docs/src/arc.base.json - Rewritten as Compute API
  • content/docs/api-docs/src/atlas.base.json - Rewritten as Infrastructure API
  • content/docs/api-docs/src/auth.base.json - Rewritten as Auth + IAM API
  • content/docs/api-docs/src/audit.base.json - Simplified to single endpoint
  • content/docs/api-docs/src/billing.base.json - Simplified to single endpoint
  • content/docs/api-docs/src/regions.base.json - Path renamed to /locations
  • content/docs/api-docs/src/notifications.base.json - Prefix updated
Source specs created (4):
  • content/docs/api-docs/src/organizations.base.json - New Organizations API
  • content/docs/api-docs/src/webhooks.base.json - New Webhooks API
  • content/docs/api-docs/src/workflows.base.json - New Workflows API (internal)
  • content/docs/api-docs/src/observability.base.json - New Observability stub
Common files updated (1):
  • content/docs/api-docs/common/schemas.json - Added Quota and Folder schemas
Generated/bundled files (22):
  • All corresponding *.json files in content/docs/api-docs/ and docs/api-docs/
  • Auto-generated MDX documentation in content/docs/(generated)/

​
Statistics

  • 38 files changed: +16,571 insertions, -77,336 deletions (net -60,765 lines)
  • 11 API specs: arc, atlas, auth, audit, billing, notifications, observability, organizations, regions, webhooks, workflows
  • 48 unique endpoints from Google Sheet MVP requirements
  • 100+ MDX pages generated via fumadocs-openapi

​
Build Pipeline

content/docs/api-docs/src/*.base.json   ← Source specs (edit these)
         ↓ (pnpm bundle-openapi)
content/docs/api-docs/*.json              ← Bundled specs ($ref resolved)
         ↓ (copied)
docs/api-docs/*.json                      ← Git-tracked copies (for CI)
         ↓ (pnpm generate-docs)
content/docs/(generated)/*.mdx            ← Generated documentation

​
Migration Notes

BetterAuth Migration Strategy
Current state: BetterAuth (better-auth.json) handles 48+ endpoints for social auth, sessions, org management, email verification, password reset. The new auth.base.json represents the target API surface — a clean, enterprise-grade abstraction. Recommended approach: 4-Phase Hybrid Adapter
  1. Phase 1 (Month 1): Adapter Facade
    • Proxy layer wraps BetterAuth endpoints into standardized {success, data, meta} envelope
    • New clients use /v1/regions/global/auth/* and /v1/regions/global/iam/*
    • Existing BetterAuth clients continue unchanged
    • Why: Zero disruption, standardizes API now
  2. Phase 2 (Months 2-3): Core Auth Service
    • Build native session management (stateless JWT, not BetterAuth tokens)
    • Implement user registration + email verification
    • Migrate sessions to JWT at token refresh (90-day forced rotation)
    • Why: JWT is portable; BetterAuth session tokens are not
  3. Phase 3 (Months 4-6): Organization & RBAC
    • Build org CRUD, member management, RBAC independently
    • Dual-write: both BetterAuth and new service (validate consistency)
    • Gradual client migration with feature flags
    • Why: Owning org/RBAC prevents vendor lock-in
  4. Phase 4 (Months 7-12): Full Migration
    • Retire BetterAuth endpoints
    • Remove adapter layer
    • Single auth backend
    • Why: Eliminates dependency, reduces attack surface
Vendor lock-in prevention principles:
  • Standardize on JWT now (not BetterAuth tokens)
  • Abstract OAuth/SSO provider config in portable format
  • Codify RBAC independently of BetterAuth internals
  • API contract versioning: OpenAPI spec IS the contract
  • Keep better-auth.json as reference until fully migrated
Alternative backends: Ory Hydra/Kratos, KeyCloak, Authentik, Hanko This migration is tracked as a separate epic (out of scope for this spec update).

​
Verification

  • ✅ pnpm bundle-openapi - 11 specs bundled successfully
  • ✅ pnpm generate-docs - 100+ MDX pages generated
  • ✅ pnpm build - Site builds successfully (209+ pages)
  • ✅ Path prefix verification - Zero singular /v1/region/ paths remain
  • ✅ Spreadsheet coverage - All 48 MVP endpoints mapped

​
References

​
Removed

  • better-auth.json - Moved to docs/hidden/better-auth.json as reference during migration

​
[Prior to 2024-02-13]

No structured changelog maintained before this date. See git history for previous changes.