Skip to main content

Tenant isolation

Tenant isolation is a product feature of Constellation OS, not an implementation detail. The design goal is that cross-tenant access has no code path, and this page walks the chain that enforces it.

From key to data plane​

Every authenticated request resolves through the same chain:

  1. Key to tenant. The validated x-api-key maps to exactly one tenant. Hostname plays no part: calling a dedicated tenant's custom domain with another tenant's key yields that other tenant's scope, not the domain owner's data.
  2. Tenant to registry entry. A registry (provided to the API as environment configuration, with no shared control-plane database to compromise) maps the tenant to its data plane: database instance, credentials secret, organization, bucket, and encryption key.
  3. Registry entry to data plane. The router holds one client per tenant, connected to that tenant's own store.

Dedicated resources per tenant​

Each tenant's data plane is physically its own:

ResourceIsolation
Time-series databaseA dedicated Timestream-for-InfluxDB instance per tenant, not a shared cluster with row filters
EncryptionA dedicated KMS key per tenant
Access tokensA scoped read/write token per tenant, held in Secrets Manager; admin credentials are used only by the provisioning tooling

On top of the physical separation, the API enforces scope in both directions: every telemetry write is stamped with the authenticated tenant server-side (a request body cannot claim another tenant), and every read is filtered to the authenticated tenant.

Fail-closed behavior​

The isolation chain fails closed at every step:

ConditionResult
Key invalid401 auth_failed
Key valid, tenant disabled403 tenant_disabled; a disabled tenant's key stops working everywhere at once
Key valid, tenant not registered in this environment503 tenant_unavailable; authentication never falls through to another tenant's plane
Tenant's data plane unreachable503 telemetry_unavailable with a retry hint; degraded, never redirected

The dedicated-stack tier​

For programs that need isolation above the data-plane level, tenants run as dedicated stacks in their own AWS accounts: their own API deployment, their own hostname on the codename.api.constellation.space pattern, their own registry containing only themselves. This is shipped practice, not roadmap; see Enterprise for the model and the spin-up process.

GovCloud environments exist as a parallel deployment family (development is live at api.dev.gov.constellation.space), keeping government workloads on government infrastructure end to end.

What to verify as a customer​

Isolation claims should be checkable. Reasonable probes:

  • Your tenant_key echoes back on every GET /topology response; it should always be yours.
  • A key for one environment must fail with 401 on every other environment.
  • Telemetry written with foreign tenant tags in the body must come back stamped with your tenant, not the claimed one.

If any of those ever fails, treat it as a critical incident and report it immediately.