---
title: Tenant
description: Tenant protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Multi-Tenant Architecture Schema

Defines the schema for managing multi-tenant architecture with:

- Global control plane: Single database for auth, org management, tenant registry

- Tenant data plane: Isolated databases per organization (UUID-based naming)

Design decisions:

- Database naming: \{uuid\}.turso.io (not org-slug, since slugs can be modified)

- Each tenant has its own Turso database for complete data isolation

- Global database stores user auth, organizations, and tenant metadata

<Callout type="info">
**Source:** `packages/spec/src/cloud/tenant.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { PackageInstallation, PackageInstallationStatus, ProvisionTenantRequest, ProvisionTenantResponse, TenantContext, TenantDatabase, TenantDatabaseStatus, TenantIdentificationSource, TenantRoutingConfig } from '@objectstack/spec/cloud';
import type { PackageInstallation, PackageInstallationStatus, ProvisionTenantRequest, ProvisionTenantResponse, TenantContext, TenantDatabase, TenantDatabaseStatus, TenantIdentificationSource, TenantRoutingConfig } from '@objectstack/spec/cloud';

// Validate data
const result = PackageInstallation.parse(data);
```

---

## PackageInstallation

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Unique installation identifier |
| **tenantId** | `string` | ✅ | Tenant database ID |
| **packageId** | `string` | ✅ | Package identifier |
| **version** | `string` | ✅ | Installed package version |
| **status** | `Enum<'installing' \| 'active' \| 'disabled' \| 'uninstalling' \| 'failed'>` | ✅ | Installation status |
| **installedAt** | `string` | ✅ | Installation timestamp |
| **installedBy** | `string` | ✅ | User ID who installed the package |
| **config** | `Record<string, any>` | optional | Package-specific configuration |
| **updatedAt** | `string` | ✅ | Last update timestamp |


---

## PackageInstallationStatus

### Allowed Values

* `installing`
* `active`
* `disabled`
* `uninstalling`
* `failed`


---

## ProvisionTenantRequest

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **organizationId** | `string` | ✅ | Organization ID |
| **region** | `string` | optional | Deployment region preference |
| **plan** | `Enum<'free' \| 'starter' \| 'pro' \| 'enterprise' \| 'custom'>` | ✅ | Tenant plan tier |
| **storageLimitMb** | `integer` | optional | Storage limit in megabytes |
| **metadata** | `Record<string, any>` | optional | Custom tenant metadata |


---

## ProvisionTenantResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **tenant** | `Object` | ✅ | Provisioned tenant database |
| **durationMs** | `number` | ✅ | Provisioning duration in milliseconds |
| **warnings** | `string[]` | optional | Provisioning warnings |


---

## TenantContext

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **tenantId** | `string` | ✅ | Current tenant database ID |
| **organizationId** | `string` | ✅ | Current organization ID |
| **organizationSlug** | `string` | optional | Organization slug |
| **databaseUrl** | `string` | ✅ | Tenant database URL |
| **plan** | `Enum<'free' \| 'starter' \| 'pro' \| 'enterprise' \| 'custom'>` | ✅ | Tenant plan tier |
| **metadata** | `Record<string, any>` | optional | Custom tenant metadata |


---

## TenantDatabase

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Unique tenant database identifier (UUID) |
| **organizationId** | `string` | ✅ | Organization ID (foreign key to sys_organization) |
| **databaseName** | `string` | ✅ | Database name (UUID-based) |
| **databaseUrl** | `string` | ✅ | Full database URL |
| **authToken** | `string` | ✅ | Encrypted tenant-specific auth token |
| **status** | `Enum<'provisioning' \| 'active' \| 'suspended' \| 'archived' \| 'failed'>` | ✅ | Database status |
| **region** | `string` | ✅ | Deployment region |
| **plan** | `Enum<'free' \| 'starter' \| 'pro' \| 'enterprise' \| 'custom'>` | ✅ | Tenant plan tier |
| **storageLimitMb** | `integer` | ✅ | Storage limit in megabytes |
| **createdAt** | `string` | ✅ | Database creation timestamp |
| **updatedAt** | `string` | ✅ | Last update timestamp |
| **lastAccessedAt** | `string` | optional | Last accessed timestamp |
| **metadata** | `Record<string, any>` | optional | Custom tenant configuration |


---

## TenantDatabaseStatus

### Allowed Values

* `provisioning`
* `active`
* `suspended`
* `archived`
* `failed`


---

## TenantIdentificationSource

### Allowed Values

* `subdomain`
* `custom_domain`
* `header`
* `jwt_claim`
* `session`
* `default`


---

## TenantRoutingConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable multi-tenant mode |
| **identificationSources** | `Enum<'subdomain' \| 'custom_domain' \| 'header' \| 'jwt_claim' \| 'session' \| 'default'>[]` | ✅ | Tenant identification strategy (in order of precedence) |
| **defaultTenantId** | `string` | optional | Default tenant ID |
| **subdomainPattern** | `string` | optional | Subdomain pattern for tenant extraction |
| **customDomainMapping** | `Record<string, string>` | optional | Custom domain to tenant ID mapping |
| **tenantHeaderName** | `string` | ✅ | Header name for tenant ID |
| **jwtOrganizationClaim** | `string` | ✅ | JWT claim name for organization ID |


---

