Documentation > API > Control-Plane

Control-Plane API

Endpoint reference for the multi-tenancy control plane: the surface that manages tenants, their database placement and provisioning, enrollment tokens that bind agents to a tenant, and the users and grants that authorize access. In the open-source core this surface is a thin stub; the working logic is a Professional+ feature (the licensed multitenancy engine, MULTITENANT_SAAS tier). The routes documented below are the engine surface, mounted under /api/control-plane when multi-tenancy is enabled and the engine is loaded. Every endpoint is gated by a JWT bearer token at the router level.

Open-Source Behavior

The OSS core ships only a stub router. When multi-tenancy is configured (multitenancy.enabled) but the licensed engine is not loaded, every path under the prefix is served by a single catch-all that returns HTTP 501 Not Implemented, indicating the licensed engine is required.

  • ANY /api/control-plane/{path} — catch-all stub; returns 501 when the licensed multitenancy engine is not loaded

When the engine is loaded it replaces this stub with the full router below. The route table is defined inside the compiled engine module; the paths shown here reflect that surface.

Status

A single read of overall control-plane state: tenant count, whether multi-tenancy is enabled, and whether self-service provisioning is turned on.

  • GET /api/control-plane/status — control-plane status (tenant count, feature flags)

Tenants

Tenant lifecycle. Listing accepts a status filter; deletion requires a confirmation slug and an explicit flag to drop the underlying database.

  • GET /api/control-plane/tenants — list tenants (filterable by status)
  • POST /api/control-plane/tenants — create a tenant
  • GET /api/control-plane/tenants/{tenant_id} — get tenant details
  • DELETE /api/control-plane/tenants/{tenant_id} — delete a tenant (confirmation slug + drop_database flag)

Placement and Provisioning

Placement records where a tenant's database lives (host, port, dbname, region, tier, OpenBAO role). Provisioning then stands up that database and its OpenBAO identity. Manual provisioning requires placement to be set first; auto-provision is the self-service path that creates placement and provisions in one step.

  • GET /api/control-plane/tenants/{tenant_id}/placement / PUT — read or upsert tenant database placement
  • POST /api/control-plane/tenants/{tenant_id}/provision — manually provision (placement required first)
  • POST /api/control-plane/tenants/{tenant_id}/auto-provision — self-service auto-provision
  • GET /api/control-plane/migration-status — pending tenant-migration status

Enrollment Tokens

Tenant-scoped tokens that bind an enrolling agent to a specific tenant. Created and revoked per tenant; consumed at agent registration.

  • GET /api/control-plane/tenants/{tenant_id}/enrollment-tokens — list a tenant's enrollment tokens
  • POST /api/control-plane/tenants/{tenant_id}/enrollment-tokens — create an enrollment token
  • DELETE /api/control-plane/tenants/{tenant_id}/enrollment-tokens/{token_id} — revoke an enrollment token

Email Domains

Per-tenant allowlist of email domains, used to scope which users may belong to a tenant.

  • GET /api/control-plane/tenants/{tenant_id}/email-domains — list allowed email domains
  • POST /api/control-plane/tenants/{tenant_id}/email-domains — add an allowed email domain
  • DELETE /api/control-plane/tenants/{tenant_id}/email-domains/{domain_id} — remove an email domain

Users and Grants

Control-plane users and the grants that bind a user to a tenant with a role. User and grant listings accept email and user_id filters respectively.

  • GET /api/control-plane/users — list users (filterable by email)
  • POST /api/control-plane/users — create a user
  • GET /api/control-plane/grants — list grants (filterable by user_id)
  • POST /api/control-plane/grants — create a user-tenant grant (role assignment)
  • DELETE /api/control-plane/grants/{grant_id} — remove a grant