Multi-Tenant Setup

Akili is a multi-tenant platform where a single deployment serves all tenants. This guide covers creating tenants, configuring resource quotas, and working with tenant-scoped operations.

Creating a Tenant

Tenant creation is an admin-only operation that provisions all required infrastructure for a new tenant.

akili tenant create acme-corp --display-name "Acme Corporation"

What Gets Provisioned

When you create a tenant, the platform automatically provisions:

Resource	What Is Created
PostgreSQL	Tenant row with RLS policies applied
Ceph RGW / S3	Bucket prefix `tenant-{id}/`
Redpanda	Base topic namespace `{slug}.*`
StarRocks	External Iceberg catalog `tenant_{slug}_catalog`
Resource groups	StarRocks resource group with default quotas

The provisioning process takes a few seconds. During this time the tenant is in PROVISIONING state and cannot be used.

# Check provisioning status
akili tenant get acme-corp

# Output:
# ID:           550e8400-e29b-41d4-a716-446655440000
# Slug:         acme-corp
# Display Name: Acme Corporation
# Status:       ACTIVE
# Created:      2026-03-16T10:00:00Z

Tenant Slug Rules

The slug is the human-readable identifier used in topic names, catalog names, and storage paths. It is immutable after creation.

Must be lowercase alphanumeric with hyphens
Must start with a letter
Length: 3 to 63 characters
Cannot be changed after creation (used in Redpanda topics and StarRocks catalogs)

Listing Tenants

# List all tenants (admin only)
akili tenant list

# As JSON
akili tenant list --json

Tenant Lifecycle

Tenants progress through a defined state machine:

State	Behavior	Transition Via
`PROVISIONING`	Resources being created	Automatic after `create`
`ACTIVE`	Fully operational	Automatic after provisioning
`SUSPENDED`	Read-only, no new deployments or executions	`akili tenant suspend`
`ARCHIVED`	No access, data retained per policy	`akili tenant archive`

Suspending a Tenant

Suspension makes the tenant read-only. Existing data remains accessible, but no new products can be created or deployed, and no pipelines execute.

# Suspend (requires --confirm)
akili tenant suspend acme-corp --confirm

Use cases for suspension:

Billing issues requiring account hold
Security investigation requiring freeze
Planned maintenance on tenant-specific resources

Reactivating a Tenant

Restore a suspended tenant to full operation:

akili tenant reactivate acme-corp

All previously deployed products resume their schedules after reactivation.

Archiving a Tenant

Archiving permanently disables a tenant. Data is retained according to the platform retention policy, then purged.

# Archive (requires --confirm, irreversible)
akili tenant archive acme-corp --confirm

Resource Quotas

Resource quotas prevent any single tenant from consuming disproportionate platform resources.

Default Quotas

Quota	Default	Description
`max_products`	100	Maximum data products
`max_connections`	20	Maximum external connections
`max_storage_gb`	500	Maximum S3 storage
`max_compute_cpu`	8	Maximum concurrent compute CPU cores
`max_compute_memory_gb`	32	Maximum concurrent compute memory

Checking Quotas

# View tenant details including quota usage
akili tenant get acme-corp --json

Quota Enforcement

Quotas are enforced at the service layer. When a tenant exceeds a quota, the API returns a 429 QuotaExceeded error:

{
  "type": "QuotaExceeded",
  "title": "Product limit reached",
  "status": 429,
  "detail": "Tenant 'acme-corp' has 100/100 products. Delete existing products or request a quota increase."
}

Working with Tenant-Scoped Operations

All CLI commands operate within the context of the authenticated user’s tenant. The tenant is determined by the tenant_id claim in the JWT token.

Switching Tenants

If your user has access to multiple tenants, use different CLI profiles:

# Configure profiles for different tenants
akili config init --api-url https://api.akili.io --profile acme
akili config init --api-url https://api.akili.io --profile globex

# Authenticate each profile
akili auth login <acme-token> --profile acme
akili auth login <globex-token> --profile globex

# Use a specific profile
akili product list --profile acme
akili product list --profile globex

Tenant Isolation Verification

You can verify tenant isolation by checking that operations are correctly scoped:

# Check authenticated identity and tenant
akili status

# Output:
# Akili Platform Status
#   OK  API Health: alive
#   OK  API Ready:  ready
#   OK  Auth:       authenticated (dev@acme-corp.com)

The tenant_id from your JWT is applied to every API request. There is no way to query or modify another tenant’s data through the CLI.

Onboarding a New Tenant

A complete tenant onboarding workflow:

# 1. Create the tenant (admin)
akili tenant create new-customer --display-name "New Customer Inc."

# 2. Verify provisioning completed
akili tenant get new-customer

# 3. Create initial connections
akili connection create \
  --name customer-db \
  --connector-type postgres \
  --config '{"host": "db.customer.com", "port": 5432, "database": "main"}'

# 4. Test connectivity
akili connection test customer-db

# 5. Initialize first data product
mkdir customer-orders && cd customer-orders
akili init --name customer-orders

# 6. Edit manifests, validate, and deploy
akili validate .akili/
akili product create --name customer-orders --namespace sales
akili product deploy customer-orders

Multi-Tenancy — isolation architecture and design
Security Architecture — authentication and authorization
akili tenant — full CLI reference