How to Structure SaaS User Accounts and Permissions

The Account Hierarchy

A well-designed SaaS account system has three levels:

• Account (organization): The top-level entity that owns all data. This is what gets billed and what your pricing tiers apply to. One account equals one customer.
• Owner: The person who created the account. They have full access to everything, including billing, user management, and all data.
• Sub-users (team members): Additional people invited to the account. They get access based on their assigned role, and they share the account's data and billing.

The platform's Account Admin system implements this hierarchy automatically. When someone registers, they get an account with a unique account ID. All of that account's data across every app is partitioned by this ID. The owner can then invite sub-users who log in with their own credentials but see the same account data.

How Registration and Login Work

The platform handles the complete authentication flow:

• Registration: New user provides email and password. The system creates an account ID, stores the credentials securely, and sets up the initial account data structure.
• Login: User provides email and password. The system looks up the account by email, verifies credentials, creates a session, and redirects to the admin panel.
• Session management: Sessions are stored in DynamoDB with configurable expiry. Each session is tied to an account ID, so every page load and API call knows exactly which customer is making the request.
• Password recovery: Handled through email-based reset tokens with time-limited expiry.

You do not need to build any of this yourself. It works out of the box when you set up a customer portal on your domain. See How to Create User Registration and Login for Your SaaS for the setup details.

Role-Based Permissions

For SaaS products used by teams, you need to control what each user can see and do. Common permission levels include:

• Admin: Full access to all features, settings, billing, and user management. Usually limited to the account owner and one or two trusted people.
• Manager: Can view and edit all data, run reports, and manage day-to-day operations, but cannot access billing or invite new users.
• Member: Can create and edit their own records but has limited access to account-wide data. Cannot change settings or manage other users.
• Viewer: Read-only access to specific data. Useful for clients, external stakeholders, or junior team members.

The platform supports role-based access control through the Account Admin system. You define which roles exist and what each role can access, and the admin panel enforces those permissions automatically in the UI.

Sub-User Management

The account owner needs to be able to invite team members, assign roles, and remove access when someone leaves. The platform's sub-user system handles this with a simple flow:

• Owner enters the sub-user's email and selects a role
• Sub-user receives an invitation and creates their own login credentials
• Sub-user logs in and sees the shared account data filtered by their role permissions
• Owner can change roles or revoke access at any time

Data Access Patterns by Role

When designing your custom app, think about what data each role needs:

• Shared data: Account settings, product configurations, and team-wide records that everyone on the account should see (filtered by role for edit permissions).
• Personal data: Records created by a specific user that only they should see, like draft content or personal notes. Use the sub-user ID as a filter.
• Aggregated data: Reports and analytics that managers and admins see but regular members do not. Restrict access by checking the user's role before returning data.

API Key Access

If your SaaS product has an API that customers can call programmatically, you need API key management in addition to user login. The platform provides API key generation and validation built into the account system. Each API key is tied to an account ID, so API requests are automatically scoped to the correct customer data.

For SaaS products that need both a web interface and an API (which is most of them), the platform handles both authentication methods. Web users log in with email and password through the admin panel. API users authenticate with an API key in their request headers. Both paths lead to the same account data.