Skip to main content

Regions & residency

Where a project's data lives is a first-class decision, not a side effect of where the developer signed up. Every project carries a region field set at creation, immutable thereafter. Cross-border data movement is opt-in and audited — never accidental. This page covers the residency model, the immutability rule, the control-plane / data-plane split, and the operational paths for jurisdiction-specific deployments.

1. Region as a sovereignty pin​

Every project pins to exactly one region at creation:

POST <orgSlug>.api.k9o.io/projects
{
"displayName": "Production",
"region": "de01",
"custodyMode": "BYOK",
...
}

The region field is drawn from a closed enum of sovereignty-pinned regions. Each region maps to a specific jurisdiction (national or supranational) and an underlying sovereign-cloud substrate (compute + storage + network within that jurisdiction). A project pinned to de01 (Falkenstein) runs on EU-based infrastructure inside the EU's data-protection regime; a project pinned to us01 (Virginia) runs on US-based infrastructure under US data-protection rules.

A region code is four characters: a country code and a two-digit sequence. It identifies the country, never the bloc or the zone (both come from the table below). A code is immutable and is never reused for a different place. The same code is used everywhere a region appears: API inputs and outputs, error messages, JWT claims, audit and billing events, SDK enums and the Console. A project's city comes from the display name in the table, not from the code.

Two groupings sit on top of the region, and they answer different questions:

  • Bloc (legal). A bloc is one country, or a set of countries that share data-protection law and treaties. Every region belongs to exactly one bloc. Moving data between regions inside one bloc needs no consent step.
  • Zone (pricing). A zone is a free trade area or single market. It sets the egress price tier. A region can belong to more than one zone. The list of zones is closed.

Neither comes from the city, which is only a display label. Bloc and zone slugs are two to twelve lowercase letters, so a slug is never mistaken for a region code.

The region enum covers 14 sovereignty-pinned regions:

RegionCity, countryBlocZoneFormer name
de01Falkenstein, Germanyeueueu-central-1
uk01London, United Kingdomukukuk-south-1
us01Virginia, United Statesusnaus-east-1
us02Texas, United Statesusnaus-central-1
us03Oregon, United Statesusnaus-west-2
ca01Montreal, Canadacanaca-central-1
ng01Lagos, Nigeriangafcftaaf-west-1
za01Johannesburg, South Africazaafcftaaf-south-1
sg01Singaporesgapacap-southeast-1
au01Sydney, Australiaauapacap-southeast-2
jp01Tokyo, Japanjpjpap-northeast-1
in01Mumbai, Indiaininap-south-1
ae01Dubai, United Arab Emiratesaememe-central-1
br01São Paulo, Brazilbrsasa-east-1

The other zone is the fallback for a region with no zone. It matches nothing, itself included, so traffic between two such regions prices as inter-zone.

The former names are listed only so you can read older logs and references. They are no longer accepted: a request that sends one is rejected like any other unknown value.

The egress-pricing tier for any pair of regions comes from their zones: same region → intra-region; different regions that share at least one zone → intra-zone; regions that share no zone → inter-zone. Singapore to Sydney crosses a bloc but shares the apac zone, so it prices intra-zone. The full pricing mapping is documented on the platform's pricing surface.

2. The immutability rule​

A project's region cannot be changed via API. PATCH <orgSlug>.api.k9o.io/projects/<projectSlug> with a region field returns INVALID_REQUEST_SHAPE (400) with context.reason: "REGION_IS_IMMUTABLE".

Why immutable? Sovereignty boundaries do not move on demand. A project pinned to de01 participates in the EU's data-protection regime as a structural fact, not a configurable preference. Allowing API-driven re-pinning would mean a single API call moves customer data across a sovereignty boundary — exactly the property the platform's positioning forecloses.

Re-pinning is operationally a project recreation: the customer creates a new project in the desired region, migrates data using their own tooling (the platform provides export endpoints; cross-project data movement is the customer's responsibility), and decommissions the old project. The operational friction is by design — it forces the migration to be a deliberate, audited, customer-led decision.

For customers whose business genuinely needs to re-pin a live project (extremely rare; typically driven by regulatory disposition changes), the operational path is a support-ticket-driven re-shard pipeline. This is not a customer-facing API; it's a one-off operational procedure with platform-side validation.

3. Control plane vs data plane​

The platform separates control-plane operations from data-plane operations, and they live in different regions:

PlaneWhat lives hereRegion
Control planeOrg / project / member metadata, billing, IdentityProvider configuration, extension registry, audit logPinned to the org's control-plane region at org creation; immutable
Data planeDocuments, files, real-time subscriptions, function executions, query resultsPinned per project at project creation; immutable

The control plane and data plane regions are decoupled. An org operating projects across three jurisdictions has a single control-plane region for operational visibility (audit log + admin Console + billing); each project's data stays inside its declared jurisdiction independently.

Control-plane region defaults to the region selected at org signup but can be set explicitly via the org-creation payload. Like project region, it is immutable after creation.

4. Cross-border policy​

By default, data does not cross region boundaries. A project pinned to de01:

  • Stores documents, files, and database state in de01 infrastructure.
  • Routes function executions to de01 compute.
  • Issues JWTs with proj_id carrying the project's region context.
  • Emits audit events into the project's de01 data-plane audit table (with a copy to the org's control-plane region).

Cross-border movement is opt-in via three mechanisms, each audited:

MechanismUse
Cross-region replicationProject-level configuration declaring read-replica regions for high-availability or cross-jurisdiction analytics; replication is one-way (declared) and audit-attributed
Audit-log exportExports to a customer-supplied SIEM endpoint cross regions per the SIEM configuration; the export is the cross-border path, not the project's primary data
Manual exportCustomer-initiated data.export operations produce signed URLs that can be retrieved from any region; the export operation itself is logged

There is no "best-effort" or "incidental" cross-border path. Every byte of customer data that leaves the declared region does so through an audited, customer-declared mechanism.

5. Region context in tokens and requests​

Every JWT carries the project's region context. Every API request carries the project context via the URL grammar (<orgSlug>.api.k9o.io/@<projectSlug>/...; see URL grammar). The gateway validates:

  1. The token's proj_id claim matches the requested project context.
  2. The targeted resource (the document being read, the file being uploaded, the function being invoked) lives in the project's region.
  3. The caller's role taxonomy and JSON-policy evaluation permit the operation.

A request that targets a resource outside the project's region is rejected at the gateway before any pillar handler runs. This isn't a soft-warning; it's a structural rejection — the gateway has no path to route the request to a resource outside the project's pinned region.

6. In-country deployments​

For customers whose compliance regime requires deployment inside a specific country we don't list as a public region, the platform supports private-jurisdiction deployments by contract (the Sovereign Control and Private Perimeter deployment architectures). The process:

  1. Customer surfaces the jurisdiction requirement to the platform team.
  2. Platform confirms a sovereign-cloud substrate is available in the country (compute + storage + network from a vendor satisfying the customer's compliance regime).
  3. A dedicated platform instance is provisioned in-country; the customer's org and projects bind to the private region as their region pin.
  4. The same API contract applies; the only difference is the underlying jurisdiction and the deployment topology (private tenant vs shared multi-tenant).

Private-jurisdiction deployments are not a customer-facing self-serve API. They are provisioned by contract with platform-side jurisdiction validation.

7. Region selection​

Every project can pin any region in the platform's region set at creation; region selection is not scaled by plan. Private-jurisdiction deployments are available by contract (see §6). The deployment architectures differ in topology, not in what a project may select:

Deployment modelTopology
CloudShared, platform-managed regions
Sovereign ControlA dedicated, isolated tenant in a platform-managed region
Private PerimeterSovereign in-country deployment on dedicated substrate

Each region is backed either by a hyperscaler (platform-managed) or, where no hyperscaler serves the jurisdiction, by an in-country sovereign deployment. The regions in the set and the pricing-zone mapping live on the pricing surface.

8. See also​