Customer Portal Requirements: A Practical Scoping Framework

A customer portal should be scoped as a controlled business workflow, not as a list of screens. Before choosing features, define which organizations and users may access which records, what actions they may take in each workflow state, where the authoritative data lives, what requires approval, and what evidence the system must retain. Those decisions determine the portal's real complexity.

This framework is for a business planning a customer, client, dealer, member, patient, partner, or vendor portal. It helps prepare a useful brief or compare proposals. It is not a security certification, privacy assessment, or legal conclusion; those requirements depend on the users, data, jurisdictions, sector, integrations, and risks of the specific system.

Start with the job that should leave email

“Give customers a login” is not a project outcome. A portal earns its place when a named user can complete a useful job without asking an employee to find information, forward a file, re-enter data, or manually confirm a decision.

At AP Works, we begin portal discovery by writing the current handoff as a seven-part operating statement:

1. Trigger: what starts the job?
2. External user: who needs something from the business?
3. Internal owner: who is accountable for the response or decision?
4. Record: what order, case, invoice, request, document, project, or account is involved?
5. Authority: which system is the source of truth?
6. Exception: what prevents the normal path from finishing?
7. Evidence: what proves the job was completed correctly?

For example: “When an invoice is issued, an authorized finance contact at the customer organization can view that organization's invoice, see the current balance from the billing system, choose an available payment method, receive a clear result, and give support a traceable reference if payment fails.” This is a hypothetical requirement, not an AP Works client case. It is more useful than “add invoices and payments” because it names the user, boundary, authority, result, and failure path.

Use a users × records × actions × states matrix

The core scoping artifact is a permission matrix. Roles alone are too broad: two people called “manager” may belong to different customer accounts, manage different locations, or have authority over different amounts. A useful requirement combines four dimensions.

This matrix should state both positive and negative rules. “A finance viewer can download invoices” is incomplete until the team also confirms whether that person may see payment methods, edit billing contacts, export all invoices, view other locations, or invite another user.

The OWASP Authorization Cheat Sheet recommends least privilege, deny-by-default behaviour, authorization checks on every request, appropriate logging, and tests for authorization logic. For a project brief, that means permissions cannot exist only as hidden buttons in the interface. The server must enforce the rule even when a user changes a URL, record identifier, request payload, or client-side state.

Model organizations before individual accounts

Many portal failures begin with a single-user data model that later has to represent real business relationships. One customer may have a parent company, multiple locations, separate billing contacts, temporary staff, an outside accountant, and an administrator who manages other users.

Resolve these questions before interface design:

• Can one person belong to more than one customer organization?
• Can an organization contain branches, departments, projects, or subsidiaries?
• Who may invite, suspend, or change the roles of other users?
• Does access come from a person's role, their relationship to a record, an amount threshold, a location, or a combination?
• What happens to open work when a user leaves or changes roles?
• Which internal staff may enter the portal as the customer, and how is that support access recorded?

A simple role list can still be useful, but it should be the output of these decisions rather than a shortcut around them. For some portals, role-based access is enough. Others need record ownership, account relationships, geography, contract terms, or risk attributes in the authorization decision.

Separate authentication from authorization

Authentication answers “is this the expected account holder?” Authorization answers “may this account perform this action on this record now?” A login system can authenticate a person correctly and still expose another customer's information if the record-level authorization rule is wrong.

Choose authentication requirements from risk, not fashion. The current NIST SP 800-63B-4, published in July 2025, defines authentication requirements at different assurance levels for government digital services. It is a useful reference, not a declaration that every commercial portal must implement the same assurance level. The portal brief should identify the sensitivity of the data, the consequence of account takeover, contractual obligations, recovery process, administrator controls, and whether phishing-resistant options are required.

Account recovery deserves the same attention as sign-in. Document who may initiate recovery, which contact channel is trusted, whether an administrator can override it, what happens when the business contact has left, and which events notify the account owner.

Define workflow states and approval authority

Approvals should attach to a specific record version and business decision. “Manager approval” is not enough if nobody can tell what the manager saw, which threshold applied, whether the underlying data changed afterward, or what happened when the request was rejected.

For each approval, record:

• the action being requested and the exact record or version;
• the requester, organization, and relevant role;
• the approval rule, threshold, or policy that selected the approver;
• the information the approver needs in plain business language;
• approve, reject, return-for-changes, cancel, expiry, and delegation paths;
• whether edits invalidate an earlier approval;
• the downstream action that is allowed only after approval.

The OWASP Transaction Authorization Cheat Sheet emphasizes that transaction authorization and its policy must be enforced on the server, where client-side changes cannot alter the result. That principle applies beyond financial transactions: a portal should not trust a hidden field or disabled button to protect an approval, refund, submission, release, or permission change.

Specify an evidence record, not a vague “audit trail”

An audit trail is useful only if the team knows which questions it must answer. “Log activity” can produce millions of technical events while still failing to show who approved a business decision.

AP Works separates operational evidence from diagnostic logging. For a material portal action, the evidence record may need:

• a stable event or request identifier;
• the actor, organization, role, and authentication context;
• the record, version, action, and before/after state;
• the server-recorded time and relevant policy decision;
• a reason, comment, attachment, or approval outcome where required;
• the downstream integration result and any retry or failure reference;
• a link to a correction or reversal rather than a silent overwrite.

Do not retain everything forever by default. The business needs a retention and access decision for each evidence class. In Canada, the Office of the Privacy Commissioner of Canada's PIPEDA principles include identifying purposes, limiting collection, limiting use and retention, accuracy, safeguards, openness, and individual access. The exact applicable privacy law can vary by organization, sector, province, and data.

Map every integration to an authority and failure mode

A portal often displays data owned elsewhere: customer details from a CRM, invoices from accounting software, inventory from an ERP, documents from storage, identities from an external provider, and payment status from a processor.

For every integration, the brief should answer:

“Integrates with the ERP” is not an acceptance criterion. “An authorized buyer sees the confirmed price for their organization, the portal labels the last successful refresh time, and a failed order submission cannot appear complete” is testable.

Write accessibility into the workflows

Portal accessibility is not limited to colour contrast and image descriptions. Forms, validation, tables, dialogs, status changes, focus order, keyboard operation, timeout warnings, error recovery, and repeated data entry affect whether a user can complete the job.

WCAG 2.2 includes requirements for identifying input errors in text, providing labels or instructions, suggesting corrections when appropriate, avoiding unnecessary redundant entry, exposing component names and states programmatically, and making status messages available to assistive technology. Turn those principles into portal acceptance tests using the actual account, payment, document, approval, and support workflows.

Choose the smallest portal release that closes a loop

An MVP should complete one valuable workflow from trigger to evidence. A dashboard that displays several disconnected numbers may look finished while leaving every real handoff in email.

A strong first release might let one customer role:

1. sign in and recover access safely;
2. see only the relevant organization and records;
3. complete one submission, approval, payment, document, or status workflow;
4. understand success, failure, and the next step;
5. give support a reference that connects to the source system;
6. leave an evidence record the business can review.

This is narrower than “launch the customer portal,” but it is a complete operating slice. It can prove whether the workflow, permissions, data connection, and support model work before more modules multiply the risk.

A hypothetical acceptance test

The following is a hypothetical example, not an AP Works client system or performance result.

Suppose a distributor wants customers to submit orders that require approval above a contract-specific threshold. One happy-path test is not enough. The release should also prove that:

• a buyer for Location A cannot read or submit an order for Location B;
• a finance-only user can view an invoice but cannot approve an order;
• an approver sees the amount, customer, items, version, and reason before deciding;
• editing an approved order either creates a new version or triggers re-approval;
• a rejected order records the reason and returns to a defined state;
• a source-system failure does not show the order as successfully released;
• support can trace the request across the portal and source system without viewing another customer's data;
• the workflow remains understandable by keyboard and assistive technology.

The negative tests are part of the requirement, not merely QA polish. They show whether the portal protects the boundaries the business approved.

What to include in a customer portal brief

• the first job that should leave email, phone, or shared folders;
• external and internal user types, organizations, locations, and delegated administrators;
• the users × records × actions × states permission matrix;
• authentication, recovery, session, and administrator requirements based on risk;
• workflow states, approvals, exceptions, expiries, cancellations, and reversals;
• source systems, data authority, synchronization, failure, and recovery rules;
• privacy purposes, data minimization, retention, access, and correction needs;
• the operational evidence required for support, disputes, compliance, and reporting;
• accessibility acceptance tests for the real workflows;
• ownership, environments, documentation, handoff, maintenance, and incident responsibilities;
• what is explicitly deferred from the first release.

If the current problem begins in spreadsheets and informal handoffs, read when to replace a spreadsheet with a custom application. It explains when the workflow has outgrown a shared file. This portal framework starts at the next decision: how to let external users interact with the system without losing control of records, permissions, approvals, and evidence.

Sources and further reading

• NIST SP 800-63B-4: Authentication and Authenticator Management
• OWASP: Authorization Cheat Sheet
• OWASP: Transaction Authorization Cheat Sheet
• W3C: Web Content Accessibility Guidelines (WCAG) 2.2
• Office of the Privacy Commissioner of Canada: PIPEDA fair information principles

Explore how AP Works scopes custom portals and business applications, or brief an application project →