Workspaces
Database-level tenant isolation with dedicated PostgreSQL databases per workspace. Full data separation, independent scaling, and zero cross-tenant risk.
I chose database-level isolation because row-level filtering makes me nervous. One missing WHERE clause and tenant A sees tenant B's data. That is not a theoretical risk. It is the actual root cause behind real-world data breaches in multi-tenant SaaS.
Every workspace in Knowably gets its own dedicated PostgreSQL database. Not a filtered view. Not a shared schema with a tenant_id column. A separate database.
This is the foundation everything else is built on.
Why This Architecture
Most multi-tenant platforms use row-level filtering. Every table gets a tenant_id column. Every query gets a WHERE tenant_id = ? scope. Every developer on the team has to remember that scope, every time, in every query.
It works until it does not. A developer writes a raw query and forgets the scope. An ORM eager-loads a relationship without the tenant filter. A background job runs outside the request context. A database export for debugging includes rows from every customer.
I did not want to build a system where one mistake from a developer - or from me - puts customer data at risk. So I went with database-level isolation instead.
A query in workspace A cannot return rows from workspace B because those rows do not exist in that database. There is no filter to forget. The isolation is enforced by PostgreSQL itself.
Three things follow from this.
No cross-tenant data leakage. It is structurally impossible. Not because the queries are careful. Because the data simply is not there.
Independent backup and restore. Each workspace database can be backed up and restored on its own. Need to restore a single customer's data after an accidental deletion? Restore their database. No impact on anyone else.
Performance isolation. A workspace running heavy search queries or processing thousands of documents does not slow down other workspaces. Each database operates independently.
What Lives Inside a Workspace
Everything related to your organization lives in your workspace database. The isolation is complete.
Knowledge bases and their connected data sources. Documents and their processed chunks, including the vector embeddings for semantic search. AI agents with their configurations, system prompts, and search strategies. Chat history with every conversation, every message, every source citation. User accounts, roles, and permissions. Media and file storage scoped to tenant-specific paths.
Background jobs are workspace-aware too. When a document processing job or a data source sync is dispatched, it automatically executes in the correct workspace database context. The framework enforces this. Developers do not have to remember it.
The only thing stored outside your workspace database is workspace metadata - name, slug, domain, subscription status - in a separate landlord database that contains no application data.
Creating a Workspace
Choose a name and a slug. The slug becomes your subdomain - acme.knowably.ai. Slugs are lowercase alphanumeric with hyphens, between 3 and 30 characters. Reserved slugs like api, admin, and auth are blocked.
Behind the scenes, Knowably creates a dedicated PostgreSQL database, runs all migrations, and seeds the default roles and permissions. This happens asynchronously through a queued job with automatic retry logic. The workspace is ready within seconds.
Each workspace can start with a configurable trial period, giving teams time to connect their data sources and explore the platform before committing.
Domain and URL Mapping
Each workspace gets a unique subdomain derived from its slug. When a user visits acme.knowably.ai, the system resolves the subdomain and connects to that workspace's database before any application code runs. By the time a controller handles the request, the connection is already scoped.
For programmatic access, API routes use a URL parameter pattern - /api/workspaces/{workspace}/... - where the workspace slug is part of the path. HTTP headers (X-Tenant-Slug, X-Tenant-Id, X-Tenant-Domain) provide flexibility for custom integrations. Session-based resolution handles seamless navigation after the initial workspace context is set.
End users get clean, branded subdomains. Developers and automated systems use whatever resolution method fits their integration.
User Management
Users exist only in their workspace database. There is no shared user table across workspaces.
The same email address can exist in different workspaces as completely separate accounts with separate passwords, roles, and access tokens. A consultant who works with multiple clients can have an account in each client's workspace without any connection between them.
Deactivation is immediate. The deactivated_at timestamp is set and all active access tokens are revoked in the same operation. The user cannot access the workspace. Their data remains intact for audit purposes.
Users are never deleted. Deactivation is reversible. Reactivating a user restores their access without losing chat history, permissions, or workspace context.
Invitation-Based Onboarding
There is no self-registration. Workspace admins control exactly who has access through an invitation system.
An admin enters one or more email addresses. The system checks each address against existing members to avoid duplicates. Before any invitation is sent, the workspace's plan limits are checked - you cannot invite more users than your subscription allows.
Each invitation generates a secure, unique token. The recipient receives an email with a link that routes them directly to the correct workspace. If the email is lost or expires, admins can resend it from the dashboard.
When a new user registers through an invitation link, they are automatically placed in the workspace with the appropriate role. This also works with OAuth registration - if a user signs in through Microsoft or GitHub, the system matches their OAuth email against the invitation.
Roles and Permissions
Access control uses Spatie Permission, a battle-tested Laravel package used in thousands of production applications. Roles and permissions are stored in each workspace's own database.
Four built-in roles cover the common patterns.
Admin has full workspace management capabilities - user management, data source configuration, agent setup, billing. The admin role has implicit access to all operations through a policy gate, so new permissions are automatically available.
Owner is the workspace creator with elevated privileges, distinct from admins who were granted their role later.
User provides standard access - chatting with agents, viewing documents, using the platform day-to-day.
Advisor is a specialized role for advisory and review workflows.
Permissions are granular. Each resource type has its own set - viewAny, view, create, update, delete - assigned to roles as needed. Because permissions live in the workspace database, different workspaces can have different configurations.
SSO and External Identity
Enterprise teams expect to authenticate through their existing identity provider. Knowably supports OAuth/SSO with Microsoft and GitHub out of the box.
Microsoft integration covers Azure AD and Entra ID. Corporate credentials, no separate password to manage.
GitHub integration serves development teams already living in the GitHub ecosystem.
Social profiles and OAuth tokens are stored per workspace. A user who belongs to multiple workspaces authenticates independently in each one.
The external ID field on user accounts enables integration with corporate directory systems. Map Knowably users to Azure AD identities, Okta profiles, or any external system. This opens the door to automated provisioning and deprovisioning synced with your identity infrastructure.
Plan Limits and Usage Tracking
Each workspace operates under a subscription plan that governs resource limits. Plans are enforced at the API level, not just the UI level. You cannot bypass limits by calling the API directly.
Limits cover the resources that matter: number of users, documents, data sources, knowledge bases, AI agents, monthly chat and message quotas, LLM connections, and storage capacity.
Usage checks happen before resource creation. These checks are enforced through middleware on the relevant API endpoints, so they apply consistently regardless of how the action is triggered.
Each workspace has its own Stripe subscription. Billing is completely independent.
A usage dashboard shows current consumption against plan limits. No surprises.
Workspace Lifecycle
Creation provisions a dedicated database, runs migrations, seeds roles and permissions, and marks the workspace as ready. The provisioning job retries automatically on failure - transient database connection issues do not leave a workspace broken.
Active use is where a workspace spends most of its life. As requests come in, the system switches database connections based on the resolved workspace. Cache namespaces, route caches, and media storage paths are all automatically scoped.
Archival. When a workspace is deleted, I rename the database instead of dropping it. Data recovery should be possible, not theoretical. The database gets an archive prefix. The data is preserved. This matters for compliance, for legal holds, and for the simple reality that someone will eventually ask to recover something they thought they did not need.
If a workspace needs to be restored, the archived database can be renamed back.
Tenant switches are logged in the landlord database for audit purposes.
Security by Architecture
The workspace model is not a security feature bolted onto a shared-database application. It is the architecture itself.
Database-level isolation means there is no query, no bug, no misconfiguration that can leak data across workspaces. The boundary is enforced by PostgreSQL, not by application code.
Cache isolation gives each workspace its own prefixed namespace. Route cache isolation ensures configurations are workspace-specific. Media storage isolation scopes all files to tenant-specific paths. Token-based authentication is scoped per workspace - a token issued in one workspace is not valid in another.
These are not just claims. Automated tests verify that agents, documents, knowledge bases, and search results do not cross workspace boundaries. Cross-tenant data leakage is tested for explicitly.
For the full security architecture, including PII detection, prompt injection prevention, and input sanitization, see the Security page.
Get Started
Every Knowably workspace starts with a free trial. Connect your data sources. Create your first agent. Invite your team.
Your data gets its own database from day one. Not after you upgrade. Not on the enterprise plan. Every workspace, every plan.