VDC Scoping

Virtual Datacenters (VDCs) provide logical isolation within a flex.plane tenant. When you scope a request to a VDC, the API only returns resources belonging to that VDC and only allows operations within its boundaries.

Set the VDC header

VDC scoping is controlled by a single HTTP header:

FlexPlane-VDC-ID: <vdc-id>

Add this header to any GraphQL request to scope it to the specified VDC:

curl -X POST https://flexplane.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -H "FlexPlane-VDC-ID: production" \
  -d '{"query": "{ vms { id name status } }"}'

This is a design choice: VDC scoping lives in the transport layer (HTTP headers), not in the GraphQL schema. Your queries and mutations look the same regardless of whether they run in VDC context or tenant-wide context. The orchestrator handles the scoping transparently via middleware.

Understand scoping behavior

The FlexPlane-VDC-ID header changes how the API resolves resources:

For example, the same vms query behaves differently depending on context:

# With FlexPlane-VDC-ID: production
# Returns only VMs in the "production" VDC
{ vms { id name status } }

# Without FlexPlane-VDC-ID
# Returns all VMs across the tenant
{ vms { id name status } }

Role requirements also shift with scoping:

• VDC-scoped operations (marked @hasRole(role: [VDC_USER]) or @hasRole(role: [VDC_ADMIN])) require the VDC header to be set and the user to have the corresponding role for that specific VDC.
• Tenant-wide operations (marked @hasRole(role: [USER]) or @hasRole(role: [ADMIN])) work with or without the VDC header.

Query available VDCs

Before scoping requests, you need to know which VDCs exist and which ones you have access to. The virtualDatacenters query returns all VDCs visible to your user:

{
  virtualDatacenters {
    id
    name
    quota {
      maxVCPUs
      maxMemoryMiB
    }
  }
}

This query is accessible to ANONYMOUS role, so it works even without the VDC header set. It returns only the VDCs your token grants access to.

To get details on a specific VDC (requires VDC-scoped access):

# With FlexPlane-VDC-ID: production
{
  virtualDatacenter(id: "production") {
    id
    name
    quota {
      maxVCPUs
      maxMemoryMiB
    }
  }
}

The context query is also useful for checking your current scoping state:

{
  context {
    id
    name
    roles
  }
}

This returns your user ID, display name, and the roles active in the current context (including VDC-specific roles when the header is set).