Concepts

Concepts: Tenants

A tenant is the isolation boundary inside an AcasoOS instance. Every operational object — users, roles, API keys, agents, chats, context, audit entries — belongs to exactly one tenant. Connections bind to a single tenant; switching tenants means switching connections.

What a tenant owns

Each tenant owns its own slice of every operational table:

dh_users, dh_roles, dh_user_rolesidentities and authorization bundles.
dh_api_keyslong-lived and session keys, owned by applications.
dh_chats and the LangGraph checkpoints behind them.
graphium memory — SKOS taxonomy concepts plus acaso:MemoryStatement/acaso:Specimen individuals in visibility-encoded KG graphs; vectors in kg_embeddings.
audit_logthe immutable event stream of writes.
Per-tenant agent overrides for any code-declared agent.

Every one of these tables has row-level security with the tenant_isolation policy forced on. The application connects as the non-privileged acaso_app role, so the policy fires on every query.

How tenants come into existence

A new tenant is created by an operator with acaso_os:admin. The console's /tenants page calls:

POST/v1/admin/tenants

curl -X POST "https://your-acaso.example.com/v1/admin/tenants" \
  -H "Content-Type: application/json" \
  -d '{"slug": "acme", "name": "Acme Co", "data_residency": "eu"}'

The bootstrap flow runs server-side, installing the default roles (admin, member, viewer) and a system user. From that point the tenant is fully usable.

Tenant fields

Field	Purpose
`slug`	Stable URL-safe handle used in every admin endpoint. Immutable.
`name`	Human-friendly display name. Editable.
`active`	When false, the tenant is soft-deactivated. Existing keys keep working until revoked.
`data_residency`	Optional region hint for downstream model-endpoint selection.
`active_templates`	List of agent templates the tenant has opted into.
`langgraph_checkpoint_retention_days`	How long the LangGraph checkpointer retains chat state.

Single-tenant connections

The console's connection model is one tenant per connection. There is no X-Acaso-Tenant-Override header in v1; an operator who needs to act in two tenants opens two connections and switches between them.

Note: Cross-tenant operations (the platform's "list active tenants" scan, retention jobs) run inside AcasoOS workers, not from the console. The console only sees one tenant at a time.

What a tenant owns

Each tenant owns its own slice of every operational table:

dh_users, dh_roles, dh_user_rolesidentities and authorization bundles.

dh_api_keyslong-lived and session keys, owned by applications.

dh_chats and the LangGraph checkpoints behind them.

graphium memory — SKOS taxonomy concepts plus acaso:MemoryStatement/acaso:Specimen individuals in visibility-encoded KG graphs; vectors in kg_embeddings.

audit_logthe immutable event stream of writes.

Per-tenant agent overrides for any code-declared agent.

Every one of these tables has row-level security with the tenant_isolation policy forced on. The application connects as the non-privileged acaso_app role, so the policy fires on every query.

How tenants come into existence

A new tenant is created by an operator with acaso_os:admin. The console's /tenants page calls:

POST/v1/admin/tenants

curl -X POST "https://your-acaso.example.com/v1/admin/tenants" \
  -H "Content-Type: application/json" \
  -d '{"slug": "acme", "name": "Acme Co", "data_residency": "eu"}'

The bootstrap flow runs server-side, installing the default roles (admin, member, viewer) and a system user. From that point the tenant is fully usable.

Tenant fields

Field

Purpose

slug

Stable URL-safe handle used in every admin endpoint. Immutable.

name

Human-friendly display name. Editable.

active

When false, the tenant is soft-deactivated. Existing keys keep working until revoked.

data_residency

Optional region hint for downstream model-endpoint selection.

active_templates

List of agent templates the tenant has opted into.

langgraph_checkpoint_retention_days

How long the LangGraph checkpointer retains chat state.

Single-tenant connections

Note: Cross-tenant operations (the platform's "list active tenants" scan, retention jobs) run inside AcasoOS workers, not from the console. The console only sees one tenant at a time.