Multi-Tenancy

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Orqestra uses a three-level hierarchy for resource isolation and cost attribution.

Hierarchy

Organization (single deployment)
  └── Namespace (ownership + cost boundary)
       └── Workspace (resource container + team collaboration)

Namespaces represent whatever ownership boundary your organization needs — business unit, domain, or team. Every namespace can carry tags like level: business-unit or cost_center: CC-4521 for reporting.

Workspaces are project-level containers within a namespace. Every resource (flow, asset, execution, release) belongs to exactly one workspace.

Isolation Model

The primary isolation boundary is the workspace. Runtime and control-plane resources carry workspace context directly or through foreign-key chains:

Repository reads fail closed where workspace scope is required. Internal service actors can use unscoped repository paths only at explicit trust boundaries.

Authorization Scope Chain

Permission checks walk from the narrowest relevant scope to broader scopes:

WORKSPACE -> NAMESPACE -> ORG -> PLATFORM

A broader affirmative grant can authorize an operation, but an absent grant at a narrow scope does not become a deny. See Identity & Access for the role and permission model.

Asset Ownership Tiers

Cross-namespace sharing uses explicit share grants that are auditable with expiry and revocation.

Cost Attribution

Costs flow upward: Execution → Workspace → Namespace → Organization.

Runtime resource limits are configured and enforced through Governance Pools, not namespace or workspace metadata. Workspace concurrency is workspace-scoped, provider TPM is scoped by organization, provider, and model, and daily cost is organization-scoped. These limits do not use namespace-to-workspace inheritance.

Secrets And Connections

Secrets and connection instances are workspace-scoped. A connection instance can bind named secret slots to workspace secret names, but runtime resolution still uses the active workspace context. This prevents a release in one workspace from implicitly reading credentials from another workspace.

See Connections & Secrets for the runtime secret resolver and backend choices.

Cross-Namespace Sharing

Cross-namespace asset access requires an explicit share grant with source namespace, target namespace, asset ID, expiry, and audit trail. Share grants do not make a workspace global; they make a specific asset visible to another namespace under a governed grant.

Global and built-in assets are handled separately from namespace share grants.

Operational Boundaries

API

# Create a namespace
POST /v1/namespaces
 
# Create a workspace
POST /v1/namespaces/{ns_id}/workspaces
 
# Add a member
POST /v1/workspaces/{ws_id}/members
 
# View cost report
GET /v1/workspaces/{ws_id}/cost-report?window_days=30
GET /v1/namespaces/{ns_id}/cost-report?window_days=30

Design Implications

• Put teams that need separate credentials, releases, and workspace members in separate workspaces.
• Put teams that share cost ownership and namespace-level administration in the same namespace.
• Use share grants for explicit reuse, not as a substitute for workspace boundaries.
• Keep provider routes, model configs, and secrets aligned with the workspace that owns the workload.
• Use cost reports and governance KPIs at workspace, namespace, and organization levels rather than flattening all reporting to a single tenant.

See Namespace & Workspace Management for operator workflows and Identity & Access for role definitions.

Namespace and workspace administration API

Use these examples with the authenticated control-plane API for your deployment. The API paths below are relative to that deployment’s base address. These advanced administration operations are separate from the portal onboarding guide.

Slugs And Tags

Namespace and workspace slugs are URL-safe identifiers:

• lowercase letters, numbers, and hyphens
• 1-64 characters
• must start and end with a letter or number

Tags are free-form metadata for reporting and search.

Runtime resource limits are configured and enforced through Governance Pools, not namespace or workspace metadata. Workspace concurrency is workspace-scoped, provider TPM is scoped by organization, provider, and model, and daily cost is organization-scoped. These limits do not use namespace-to-workspace inheritance.

Creating a Namespace

# Via CLI
orqestractl namespace create \
  --slug data-engineering \
  --display-name "Data Engineering" \
  --org-id "$ORQESTRA_ORG_ID"
 
# Via API
POST /v1/namespaces
{
  "slug": "data-engineering",
  "display_name": "Data Engineering",
  "org_id": "00000000-0000-0000-0000-000000000001",
  "tags": {"level": "business-unit", "cost_center": "CC-4521"}
}

Creating a namespace requires namespace.create at organization scope. The API records a namespace.created governance audit event.

Creating a Workspace

POST /v1/namespaces/{namespace_id}/workspaces
{
  "slug": "fraud-detection",
  "display_name": "Fraud Detection",
  "service_lane": "standard",
  "description": "ML-powered fraud detection pipeline"
}

The service-lane values are standard, guided, and restricted. Apply the release and policy requirements configured for the selected lane; the name alone does not establish that a workload is approved or ready to run.

Creating a workspace requires workspace.create on the namespace. The API records a workspace.created governance audit event.

Listing And Updating

# List namespaces visible to the actor
GET /v1/namespaces?limit=50&offset=0
 
# Read namespace details
GET /v1/namespaces/{namespace_id}
 
# Update namespace metadata
PATCH /v1/namespaces/{namespace_id}
{
  "display_name": "Data Platform",
  "tags": {"level": "business-unit"},
  "status": "active"
}
 
# List workspaces visible in a namespace
GET /v1/namespaces/{namespace_id}/workspaces?limit=50&offset=0

Namespace deletion is allowed only when the namespace has no workspaces. A namespace that still owns workspaces returns 409.

Managing Members

# Add a developer
POST /v1/workspaces/{workspace_id}/members
{
  "user_ref": "alice@company.com",
  "role": "developer"
}
 
# List members
GET /v1/workspaces/{workspace_id}/members
 
# Remove a member
DELETE /v1/workspaces/{workspace_id}/members/alice@company.com

Workspace membership controls the resources inside a workspace. Namespace admins can create and operate workspaces in their namespace, but workspace membership still determines which project resources a user can inspect or mutate. See Identity & Access for role boundaries and the scope chain.

Cross-Namespace Sharing

To share an asset from one namespace with another:

POST /v1/share-grants/
{
  "source_namespace_id": "...",
  "target_namespace_id": "...",
  "asset_id": "...",
  "expires_at": "2026-12-31T00:00:00Z"
}

Revoke with DELETE /v1/share-grants/{grant_id}.

Creating a grant requires asset-share authority on the source namespace and visibility of the target namespace. The asset must belong to the source namespace. Source and target must be different, and both are checked against the authorized scope of the actor.

Share grants are for namespace-owned assets. Global or built-in assets are not shared through namespace grants. Grant and revoke actions emit governance audit events.

Browsing the Asset Catalog

View assets across all namespaces (metadata only):

GET /v1/catalog/assets?asset_kind=model_config&search=gpt

The catalog returns built-in, organization-shared, namespace-shared, and workspace-scoped assets that the actor can see. Cross-namespace visibility comes from explicit share grants.

Cost Reports

# Workspace-level
GET /v1/workspaces/{id}/cost-report?window_days=30
 
# Namespace aggregate with per-workspace breakdown
GET /v1/namespaces/{id}/cost-report?window_days=30