Projects

Projects let you group cloud resources into logical units — teams, environments, or business units — within your organisation. Many platform resources (KMS keys, secrets, DNS zones, VPCs, Kubernetes clusters, and others) can be scoped to a project when you set a project context on API calls.

Project-scoped IAM policies build on projects: they define who can do what on which resources within a specific project.

Projects require the projects feature gate on your organisation.

Getting started

API reference

Projects API endpoints and headers

IAM policies

Project-scoped access control

Availability and prerequisites

Requirement	Customer impact
Organisation feature gate: `projects`	Must be enabled. If disabled, project and IAM policy APIs return `403`
At least one project	IAM policies are defined per project
Organisation membership	Callers must be authenticated organisation members, service accounts, or OIDC clients with appropriate org access

Dependency chain:

  → projects feature gate enabled
    → at least one project created
      → IAM policies can be defined and bound
        → principals use X-Project-Identity on resource APIs

Organisation vs project

Layer	Purpose	API / header
Organisation	Billing, membership, org-wide roles	`X-Organisation-Identity`
Project	Logical grouping of resources; optional parent/child tree	`/v1/projects`
IAM policy	Project-scoped RBAC (rules + bindings + conditions)	`/v1/projects/iam/policies`
Organisation role	Org-wide RBAC (unchanged model)	`/v1/iam/roles` — see RBAC roles

Project hierarchy

Projects support a single parent per project with unlimited depth. Build the tree client-side from the flat project list using each project’s parentProject reference.

Organisation
└── Project "platform"
    ├── Project "team-a"
    └── Project "team-b"
        └── Project "team-b-staging"

Use projects to mirror teams, environments, or business units. A child project inherits replicated IAM policies from ancestor projects when configured — see Policy replication.

Creating a project

When you create a project, the platform provisions default system IAM policies and binds the creating principal to the admin policy.

Side effect	Description
Default system IAM policies	Platform-managed policies mirroring organisation default role templates (including admin)
Creator binding	The creating principal is automatically bound to the project admin policy
Ancestor replication	If a parent project is set, replicated policies from ancestor projects are synced into the new project

Parent project

Optional at create via parentProjectIdentity
Can be changed or cleared on update
Parent must exist in the same organisation; cycles are rejected

Project context on resource APIs

Many platform resources are project-scoped when X-Project-Identity is set (or an OIDC project claim / ?project= query parameter is provided). IAM policy bindings on that project then contribute to permission checks.

Context	Behaviour
With project context	Organisation roles still apply, plus IAM policy bindings on the active project
Without project context	Only organisation-scoped resources and organisation roles apply

Project resolution order: OIDC claim project → X-Project-Identity → ?project= query parameter.

Deleting a project

Delete returns 400 if the project still has dependent resources. Remove or migrate resources before deleting the project.