Tenants & Multi-Tenancy

Multi-tenancy is an Enterprise-only feature that lets a single Sophon Gateway host multiple isolated workspaces. Each tenant has its own users, agents, memory, workflows, documents, connections, and audit trail — completely separated at the data layer via EF Core global query filters.

Use tenants when you need to host different departments, customers, or subsidiaries on shared infrastructure with guaranteed isolation.

What gets isolated per tenant

Every tenant-scoped resource is tagged with a TenantId column and EF Core's global filter ensures queries can't cross boundaries. Scoped resources:

• Users and their assignments
• Agents (SOUL.md, tool allowlists, configurations)
• Memory entries (user-scope + agent-scope)
• Daily logs
• Sessions and chat history
• Workflows and their runs
• Cron jobs
• Documents and the vector index
• Connections (OAuth / API keys)
• Channel configurations
• Skills (which are enabled; the code is shared)
• Webhooks
• Insights and metrics
• Audit logs
• Sophon Nodes paired to the tenant

Not isolated (shared across tenants):

• The Sophon Gateway binary and its configuration
• Installed skills' code (the toggle is per-agent per-tenant)
• License and tier
• System-level settings
• The vault backend (though vault entries themselves are tenant-scoped)

Creating a tenant

Admin → Tenants → New.

• Name — display name (e.g., "Acme Corp", "Marketing")
• Slug — URL-safe identifier (e.g., acme). Used in API paths.
• Description
• Initial admin — which existing user (or new invite) will be Admin in this tenant
• Tier override — optional; default inherits from the Gateway's global tier. You can drop a tenant to a lower tier if needed for cost allocation.

Save. The new tenant appears in the tenant switcher in the top nav.

From the CLI

sophon tenant create --name "Acme Corp" --slug acme
sophon tenant list
sophon tenant describe acme
sophon tenant delete acme    # requires confirmation, wipes all tenant data

Tenant context resolution

Every authenticated request includes a tenant in its context. The context is resolved in this order:

1. JWT claim — if the user's JWT has a tenant claim, that wins.
2. Header — X-Sophon-Tenant: <slug> for API clients that support multiple tenants.
3. URL prefix — /api/tenants/<slug>/… for explicit tenant routing.
4. User's default tenant — if the user has only one tenant assignment, it's used implicitly.

If the resolver can't pick one and the user has multiple, the request returns 400 with a tenant-required error.

Assigning users to tenants

A user can belong to one or many tenants. Their role is set per-tenant — they can be Admin in Tenant A and Viewer in Tenant B.

Dashboard

Admin → Tenants → <tenant> → Users → Add. Pick existing user or invite a new one, assign role.

CLI

sophon tenant assign --tenant acme --user <id> --role Admin
sophon tenant unassign --tenant acme --user <id>
sophon tenant users acme

The tenant switcher

Users with multiple tenant assignments see a dropdown in the Dashboard's top nav. Switching tenants:

• Reloads the sidebar and page to reflect the new tenant's data
• Preserves authentication (no re-login)
• Logs the switch in the audit log with the source and destination tenants

Resource quotas

Per-tenant limits, configured at tenant creation or later:

Quotas are soft by default (warn at 80%, block at 100%); configurable per tenant.

Tenant-scoped roles

Custom roles can be tenant-scoped — a role defined in Tenant A isn't visible from Tenant B. Global roles (created by a Gateway-level Admin) are visible to all tenants.

This lets each tenant define their own role vocabulary ("Marketing Editor", "Sales Manager") without polluting other tenants' role lists.

See RBAC for scope details.

Cross-tenant operations

Intentionally restricted. The only cross-tenant operations are:

• Global Admin actions: creating / deleting tenants, managing licenses, system settings
• User reassignment — moving a user between tenants (explicit admin operation, audited)
• Reports — aggregated usage across tenants, for billing / capacity planning

There's no way for an agent or workflow to reach across tenant boundaries. This is a hard guarantee enforced by query filters.

Data export per tenant

Each tenant can export all its data:

sophon tenant export --tenant acme --out acme-backup.zip

Exports include:

• User list (with hashed passwords — importable into a fresh Sophon)
• All agents, workflows, cron jobs, skills (enablement list)
• Memory entries and daily logs
• Documents (raw files + extracted text)
• Connections (credentials redacted for security)
• Audit log

Restore into a fresh tenant:

sophon tenant import --into-tenant new-acme acme-backup.zip

Deleting a tenant

Admin → Tenants → <tenant> → Delete. Requires:

• Typed confirmation of the tenant name
• Optional export beforehand
• Requires Global Admin role

Deletion cascades: all users assigned only to this tenant are deleted too (users with other tenant memberships have only this membership removed). All tenant-scoped data is permanently removed. Audit log entries are retained per compliance retention policy but with tenant name redacted.

Vault considerations

By default, the credential vault is shared infrastructure — but vault entries are tenant-scoped via namespacing: tenant:<slug>/user:<id>/conn:<name>. External backends (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) receive the full namespaced key.

For stronger isolation, Enterprise deployments can configure per-tenant vault backends:

{
  "Sophon": {
    "Tenants": {
      "acme": {
        "Credentials": {
          "Vault": "AzureKeyVault",
          "VaultUri": "https://acme-vault.vault.azure.net/"
        }
      }
    }
  }
}

Each tenant then has its own isolated secret store.

Audit

Every tenant-related action is audited with both source and target tenant when applicable (user moves, cross-tenant admin actions). Admin → Audit → Tenant filter scopes the log to one tenant.

Where to go next

• Users — creating users and assigning tenant memberships
• RBAC — tenant-scoped roles
• Licensing — license allocation across tenants