Client portal architecture guide
How should you design a client portal API?
Design the portal API as a controlled application boundary that resolves customer identity, enforces organisation and object-level authorisation, presents stable customer-facing contracts, and handles business-system failure safely.
The recommended architecture
Place a server-side application API between the customer interface and internal systems. Let that API own customer context, permissions, validation, workflow orchestration and the portal-facing data model. Keep the CRM, ERP, accounting platform, data warehouse and specialist systems responsible for the records and rules they genuinely own.
The browser should ask for a customer task, not assemble one by calling internal systems directly. This gives the portal one place to enforce access, hide unstable source-system details and decide what happens when a dependency fails.
01
Separate the customer experience from source systems
| Layer | Responsibility | Keep out |
|---|---|---|
| Customer interface | Interaction, input, accessible feedback and local presentation state | Secrets, trusted permission decisions and direct source credentials |
| Portal API | Session context, customer scope, validation, customer-facing contracts and workflow entry points | Blind trust in identifiers or roles supplied by the browser |
| Application services | Business use cases, policy decisions, orchestration, idempotency and audit events | Interface-specific formatting scattered through domain rules |
| Integration services | Source adapters, retries, mapping, queues, webhooks and dependency health | Leaking vendor response shapes into every portal screen |
| Systems of record | Authoritative customers, invoices, orders, cases, documents or measures | Customer-facing assumptions they were not designed to support |
02
Design contracts around customer tasks
A portal contract should express the information and actions a customer needs, even when those come from several systems. Prefer endpoints and commands that make business intent clear, such as retrieving an account overview, submitting a service request or approving a specific version.
- Use stable resource names and consistent request, response and error shapes.
- Return only the fields required for the customer task.
- Use opaque external identifiers when internal identifiers should remain private.
- Define pagination, filtering, sorting and maximum result sizes.
- Make dates, timezones, currency, units and data freshness explicit.
- Describe validation errors without exposing internal implementation details.
- Use idempotency for customer actions that must not run twice.
- Document lifecycle states and valid transitions.
- Prefer additive evolution and publish deprecation timelines for breaking changes.
03
Separate authentication, customer context and authorisation
Identity
Who is making the request?
Validate the session or token using the intended issuer, audience, signature, expiry and flow.
Membership
Which organisation are they acting for?
Resolve an active server-side membership and handle users who belong to several accounts explicitly.
Object
May they access this record?
Scope every lookup to the authorised organisation and confirm any relationship required by policy.
Action
May their role perform this operation?
Apply function, state, value, mandate and approval rules before changing data.
OWASP identifies broken object-level authorisation as a leading API risk. A random identifier is not a permission check. Every function that uses a client-supplied identifier to access a record needs a server-side authorisation decision.
Read the focused guide on giving each customer access only to their own data and the wider client portal security guide.
04
Choose an integration pattern per business need
| Pattern | Useful for | Main design concern |
|---|---|---|
| Synchronous API | Current information or a fast action with an immediate result | Timeouts, dependency failure and safe customer feedback |
| Background command | Long-running requests, exports, imports or unreliable dependencies | Idempotency, durable status and retry limits |
| Event or webhook | Keeping portal state current after a source-system change | Authenticity, replay, ordering, duplication and reconciliation |
| Scheduled synchronisation | Data where a defined delay is acceptable | Freshness visibility, incremental loading and missed runs |
| Portal read model | Fast customer views assembled from several systems | Ownership, staleness, correction and rebuild capability |
Do not make a customer wait on a chain of internal systems when the work can be accepted safely and processed in the background. Do not report success until the responsible system has accepted the action or the portal clearly labels it as pending.
05
Design failure before the happy path is complete
- Set bounded timeouts for every dependency.
- Retry only failures that are safe and likely to recover.
- Use idempotency keys or business deduplication for repeatable commands.
- Move long or fragile work to durable queues.
- Record a customer-visible state for accepted, processing, completed and failed work.
- Use circuit breaking or load shedding where dependency failure could cascade.
- Reconcile portal records against systems of record.
- Give staff an exception queue with ownership and safe retry controls.
- Preserve submitted customer data when recovery is possible and appropriate.
- Never expose stack traces, secrets or internal network details in errors.
06
Operate the API as a customer service dependency
Monitor the journey, not only server health. Useful signals include request volume, latency by operation and dependency, authorisation denials, validation failures, queue age, retry volume, data freshness and the rate of customer actions reaching a completed business outcome.
Maintain an inventory of endpoints, consumers, owners, data classification, authentication method and lifecycle state. Remove obsolete endpoints and credentials through a controlled process. Audit sensitive exports, approvals, access changes and privileged support actions without placing confidential payloads or tokens in logs.
07
Client portal API design checklist
- Define the customer tasks. Name the information and actions the API must support.
- Map systems of record. Assign ownership for every field, document, status and command.
- Model organisations and roles. Include memberships, branches, delegates and support users.
- Write the authorisation policy. Cover object, function, state and value-level decisions.
- Design the contract. Specify fields, errors, pagination, freshness and lifecycle states.
- Select integration patterns. Choose synchronous, queued, event-driven or replicated access per need.
- Design failure and recovery. Include timeout, retry, duplicate, partial success and unavailable systems.
- Threat-model the interface. Test identifier tampering, excessive data, privilege escalation and abuse.
- Add observability. Connect technical signals to customer completion and internal ownership.
- Plan change. Inventory consumers, support additive evolution and manage deprecation.
Use the full client portal implementation checklist to connect API design with customer research, testing, rollout and support.
Sources
Primary technical sources reviewed
This draft was checked on 21 August 2026 against:
- OWASP API1:2023 Broken Object Level Authorization
- OWASP API5:2023 Broken Function Level Authorization
- RFC 9700: Best Current Practice for OAuth 2.0 Security
- NIST SP 1800-35: Implementing a Zero Trust Architecture
Apply the controls proportionately to the data, transaction and threat model. No framework replaces project-specific architecture and security review.
Questions
Frequently asked questions
What is a client portal API?
A client portal API is the controlled application interface that supplies customer-specific data and accepts authorised customer actions. It should present a stable portal model while protecting the internal systems, identifiers and workflows behind it.
Should the portal call ERP and CRM APIs directly from the browser?
Usually not. A server-side portal or backend-for-frontend layer should authenticate the user, apply customer and role permissions, validate requests, coordinate source systems and return only the data required by the interface.
How should a portal API enforce customer separation?
Resolve the authenticated user to an active organisation membership and role, then enforce that context in every server-side query, object lookup, action and file request. Never trust a customer or tenant identifier supplied by the browser without verifying the user's relationship to it.
Does every portal need microservices?
No. A modular application can provide a clear API, integration boundaries, background jobs and reliable operations without the deployment complexity of many services. Split services when ownership, scaling, risk or independent change genuinely requires it.
How should API changes be versioned?
Prefer additive changes and explicit deprecation. Version only when a breaking contract cannot be avoided, identify consumers, publish a migration path, observe old-version usage and remove it through a controlled process.
Map the portal boundary
Bring the customer journey, source systems and difficult access rules.
LCR can help define a focused portal API, tenant-aware authorisation model and integration approach around the systems your business already uses.