Client portal architecture guide
How do you build a multi-tenant client portal?
Build a multi-tenant portal around an explicit organisation, membership and permission model. Resolve the active customer on the server, scope every record and action to that customer, and carry the same boundary through files, integrations, jobs, caches and administration.
The short answer
A multi-tenant client portal needs three distinct concepts: a person, an organisation and the person's membership in that organisation. Permissions belong to the membership or a role within it, not automatically to the user everywhere.
Every protected request should resolve a trusted active organisation, confirm that the person belongs to it, authorise the action and retrieve the resource inside that boundary. The same rule applies to API responses, downloads, exports, search, notifications, queues, scheduled jobs and internal support tools.
Start with one consistent model unless a verified customer or regulatory requirement justifies dedicated infrastructure. Strong logical isolation can be appropriate for many B2B portals, but the decision should follow the data, actions, contracts and operating model.
01
Define the tenancy model before designing screens
The word “customer” is often too vague for software design. One customer may contain a head office, branches, departments, contracts and several user roles. Write down the real commercial and operational relationships first.
| Concept | Meaning | Example questions |
|---|---|---|
| Person | An individual identity that can sign in | Can the same email represent one person across several organisations? |
| Organisation | The customer boundary that owns or may access resources | Is a branch separate, nested or simply an attribute? |
| Membership | The relationship between a person and an organisation | When does access start, expire or require approval? |
| Role | A reusable set of permitted actions | Can a finance user view invoices but not submit operational requests? |
| Resource | A record, file or action protected by the boundary | Which organisation owns it, and can ownership ever change? |
A person who works with two customer organisations should normally have two memberships. Switching organisation changes the active context; it does not combine the organisations or grant the union of both permission sets.
02
Choose an isolation pattern that matches the risk
Shared tables
Tenant key on each resource
Operationally efficient and common for SaaS-style portals. It requires disciplined query scoping, constraints, policies and testing throughout the application.
Separate schemas
Logical database separation
Can strengthen administrative separation while keeping one database platform. Migrations and cross-tenant operations become more involved.
Separate databases
Dedicated data stores
Useful when contractual, scale, residency or blast-radius requirements justify stronger separation. Provisioning, reporting and maintenance cost more.
Dedicated instance
Application and data isolation
Supports exceptional customer controls or release needs, but reduces the economic and operational benefits of a shared product.
The storage pattern does not replace authorisation. Even a separate database needs correct user-to-customer mapping, protected credentials and controlled administrative access. A shared database can be appropriate when the portal enforces the boundary consistently and its assurance matches the risk.
03
Separate authentication, membership and authorisation
Authentication confirms the person. It does not prove that the person may access a particular customer record. The server should derive the permitted organisations from trusted membership data and should never accept a tenant identifier from the browser without validating that relationship.
- Default to no access until an active, valid membership grants it.
- Authorise every protected request, including direct API and file requests.
- Check both the action and the specific resource inside the active organisation.
- Model customer administrators separately from platform administrators.
- Make support impersonation explicit, limited and auditable if it is required.
- Revoke sessions or re-evaluate access when important memberships change.
See the client portal security guide for the wider security and operational controls.
04
Carry the tenant boundary beyond database queries
Cross-customer exposure often occurs outside the obvious record view. Review each of these paths:
Store ownership metadata and check it before issuing a short-lived link or streaming a file.
Include the organisation boundary in indexing, filtering and result retrieval.
Background work should carry an immutable organisation identifier and re-check important resources.
Include the tenant and relevant permission context so one customer's response cannot serve another.
Large reports and bulk downloads need the same field and record controls as the interface.
Do not trust customer identifiers received from another system without a controlled mapping.
The portal integrations guide explains how source-system ownership and failure handling affect this design.
05
Build tenant-aware administration and operations
Internal teams need to create organisations, invite or remove users, resolve mapping errors and support customers without bypassing the security model. Administrative tools should show the active customer context prominently and require stronger controls for high-impact actions.
- Record who created, changed, suspended or deleted memberships and roles.
- Test onboarding, offboarding, mergers, branch changes and contract expiry.
- Provide a safe way to reconcile records that fail to map to a customer.
- Monitor cross-system jobs by organisation without exposing unnecessary customer data in logs.
- Design backups and restoration so one customer's recovery does not silently affect another.
- Measure activation and target-workflow completion at organisation and user level.
06
A practical implementation roadmap
- Map the customer hierarchy. Identify organisations, branches, contracts, people, roles and exceptional relationships.
- Classify resources and actions. Define ownership and permitted operations for records, files, reports and workflows.
- Select the isolation pattern. Balance risk, contractual requirements, scale, operations and cost.
- Build the access foundation. Implement membership, active context, server-side policies, audit and administration.
- Prove one end-to-end workflow. Include the source integration, background processing, notifications and support path.
- Test hostile boundaries. Change identifiers, roles, organisation context and direct URLs across every interface.
- Pilot with representative customers. Include a simple customer and one with multiple users, branches or roles.
07
When is multi-tenancy not the right first step?
Do not introduce a complex multi-tenant platform when the product has one internal organisation, a small known user group and no customer data boundary. A simpler role model may be enough.
Dedicated customer environments can also be the better choice where contracts require them, customers need independent release control, data residency differs materially, or customer-specific functionality would make a shared application fragile. Compare the full operating cost and change process rather than treating either model as automatically more secure.
For the overall capability and delivery context, see custom client portal development.
Questions
Frequently asked questions
What is a multi-tenant client portal?
A multi-tenant client portal serves multiple customer organisations from one application while keeping each organisation's users, data and actions within the correct customer boundary.
Does multi-tenant mean every customer shares one database?
No. Tenancy is a logical access model, not a single storage choice. Customer data can share tables with tenant keys, use separate schemas, use separate databases or combine these patterns according to risk and operational needs.
Can one user belong to more than one customer organisation?
Yes, if the business relationship requires it. Model membership separately from the user identity so one person can hold distinct roles in several organisations without merging those organisations' data.
How do you prevent cross-tenant data access?
Resolve the active organisation from trusted membership, scope every server-side query and action to that organisation, authorise the requested resource, protect files and background jobs with the same boundary, and test deliberate cross-tenant access attempts.
When is a single-tenant architecture better?
Dedicated instances may be better when a customer requires strong infrastructure isolation, unique release schedules, unusual residency controls or extensive customer-specific changes and will support the additional operating cost.
Design the boundary first
Bring the customer types, roles and data relationships.
Share how customer organisations, branches and users relate, what each role must access, and which systems hold the source data. LCR will help define a focused tenancy model and the highest-risk flows to prove first.