Users are the people who access your Catalio workspace. Each user has a defined role that controls their permissions, an authentication provider that manages their identity, and a status that determines whether they can sign in. Effective user management ensures the right people have the appropriate access to create, edit, and view your product requirements.
What is a User?
A user represents an authenticated person who can access your organization’s Catalio workspace. Users are associated with:
- Email address: Unique identifier for authentication
- Authentication provider: How they sign in (Auth0, WorkOS, or Clerk)
- Role: What permissions they have (Admin, Editor, Contributor, or Viewer)
- Organization: Which workspace they belong to
- Profile: Name, language preferences, and timezone
- Status: Whether they can currently sign in (Active or Suspended)
Every user belongs to exactly one organization at a time. Organizations provide complete data isolation—users in Organization A cannot see any data from Organization B.
User Roles Explained
Catalio uses four distinct roles to control what users can do. Each role grants progressively more permissions:
Viewer
Read-only access to all content
Viewers can:
- ✅ Browse and search requirements, personas, use cases, and test cases
- ✅ View project structure and component relationships
- ✅ Read discussions and comments
- ✅ Export data for external analysis
- ✅ Access AI-powered semantic search
Viewers cannot:
- ❌ Create, edit, or delete any content
- ❌ Change project structure
- ❌ Manage users or organization settings
- ❌ Modify workflows or processes
Best for: Executive sponsors, clients, external stakeholders, compliance auditors, and anyone who needs visibility without editing capabilities.
Example Scenario:
Sarah, a Product Sponsor, needs to review the requirements roadmap before approving budget. She has Viewer access to understand progress and priorities without accidentally modifying specifications.
Contributor
Create and edit your own content
Contributors can:
- ✅ Create new requirements, personas, use cases, and test cases
- ✅ Edit and delete content they created
- ✅ Add comments and participate in discussions
- ✅ Use AI features to enhance their requirements
- ✅ Export data and generate reports
Contributors cannot:
- ❌ Edit or delete content created by others
- ❌ Manage users or organization settings
- ❌ Archive or restore content
- ❌ Modify global workflows
Best for: Development team members, QA engineers, technical writers, and domain experts who contribute requirements but don’t need full editorial control.
Example Scenario:
Marcus, a Software Developer, creates test cases for the features he’s implementing. He can add, edit, and manage his test cases but cannot modify requirements written by the business analysts.
Editor
Full control over all content
Editors can:
- ✅ Create, edit, and delete ALL requirements and related content
- ✅ Manage project structure and components
- ✅ Archive and restore content
- ✅ Configure workflows and processes
- ✅ Assign work to team members
- ✅ Use all AI features
- ✅ Bulk update and manage content
Editors cannot:
- ❌ Manage users or invite team members
- ❌ Change organization settings
- ❌ Access billing or subscription settings
- ❌ Configure authentication providers
Best for: Product managers, business analysts, requirement owners, and team leads who need to manage the entire requirement lifecycle.
Example Scenario:
Jessica, a Senior Business Analyst, manages the requirements backlog for three major projects. As an Editor, she organizes requirements across components, maintains traceability, and ensures quality standards are met across all contributions.
Admin
Complete organizational control
Admins can:
- ✅ Everything Editors can do
- ✅ Invite and manage users
- ✅ Assign roles to team members
- ✅ Suspend or reactivate user accounts
- ✅ Configure organization settings
- ✅ Manage authentication providers
- ✅ Access audit logs and usage analytics
- ✅ Configure AI accessibility settings
- ✅ Manage integrations and API keys
Best for: Organization owners, system administrators, and senior stakeholders responsible for workspace governance and security.
Example Scenario:
David, the VP of Product, owns the Catalio workspace for his division. As an Admin, he invites new team members, configures SSO with the company’s Auth0 tenant, and ensures compliance with data access policies.
Role-Based Access in Practice
Quick Reference Table
| Capability | Viewer | Contributor | Editor | Admin |
|---|---|---|---|---|
| View all content | ✅ | ✅ | ✅ | ✅ |
| Create content | ❌ | ✅ | ✅ | ✅ |
| Edit own content | ❌ | ✅ | ✅ | ✅ |
| Edit all content | ❌ | ❌ | ✅ | ✅ |
| Delete content | ❌ | Own only | ✅ | ✅ |
| Manage structure | ❌ | ❌ | ✅ | ✅ |
| Manage users | ❌ | ❌ | ❌ | ✅ |
| Configure organization | ❌ | ❌ | ❌ | ✅ |
| Access audit logs | ❌ | ❌ | ❌ | ✅ |
Permission Inheritance
Roles follow a hierarchical permission model:
Admin ⊃ Editor ⊃ Contributor ⊃ Viewer
This means:
- Admins can do everything Editors, Contributors, and Viewers can do
- Editors can do everything Contributors and Viewers can do
- Contributors can do everything Viewers can do
When assigning roles, choose the minimum role needed for someone’s responsibilities. This follows the security principle of least privilege.
Authentication Providers
Catalio supports multiple ways for users to authenticate and sign in:
Auth0 (OAuth2)
Default enterprise authentication
Auth0 provides secure, standards-based authentication using OAuth2 and OpenID Connect protocols. When users sign in with Auth0:
- They’re redirected to your organization’s Auth0 tenant
- They authenticate using configured identity providers (Google, Microsoft, Okta, etc.)
- Auth0 returns user profile information and organization membership
- Catalio creates or updates the user account based on Auth0 data
Key features:
- Single Sign-On (SSO) integration with corporate identity providers
- Multi-factor authentication (MFA) support
- Automatic user provisioning from organization membership
- Role assignment based on Auth0 metadata
- Enterprise-grade security and compliance
Role mapping: Catalio reads the user’s role from Auth0 organization metadata. Configure roles in your Auth0 tenant under Organization → Members.
WorkOS (Planned)
WorkOS will provide enterprise SSO with simplified integration for services like Okta, Azure AD, and Google Workspace.
Clerk (Planned)
Clerk will offer modern authentication with built-in user management UI and session handling.
MCP OAuth2 (Programmatic Access)
For AI agents and automation
MCP (Model Context Protocol) uses OAuth2 authentication via Auth0 for programmatic access:
- AI agents like Claude Desktop and Claude Code
- Custom integrations with external tools
- Headless requirement management workflows
How MCP OAuth2 works:
- MCP client connects to the Catalio MCP endpoint
- Server returns 401 with OAuth2 discovery metadata (RFC9728)
- Client authenticates with Auth0 using your existing Catalio credentials
- Access tokens inherit your user’s role and organization access
- Tokens are automatically refreshed when needed
Security considerations:
- Uses industry-standard OAuth2 with Auth0 as identity provider
- Access tokens are short-lived and automatically refreshed
- No need to manage or rotate API keys manually
- Same credentials as web login for seamless experience
- Full audit trail through Auth0 logs
Example use case:
A business analyst configures Claude Code to connect to Catalio’s MCP endpoint. When Claude attempts to access requirements, the analyst is prompted to sign in via Auth0. After authentication, Claude can access requirements using the analyst’s permissions, enabling semantic search and requirement analysis in conversational workflows.
User Status Lifecycle
Users can be in one of two status states:
Active
Normal operational status
Active users can:
- Sign in to Catalio
- Access content according to their role
- Create, edit, or view requirements
- Use MCP OAuth2 for programmatic access via AI agents
- Receive notifications and updates
This is the default status for new users.
Suspended
Temporarily disabled access
Suspended users:
- Cannot sign in to Catalio
- Cannot use OAuth2 tokens for MCP access
- Cannot receive notifications
- Retain their historical contributions and audit trail
- Can be reactivated at any time by an Admin
Why suspend instead of delete?
- Compliance: Maintain complete audit trails for regulatory requirements
- Attribution: Preserve authorship on historical requirements
- Reversibility: Easily restore access for returning team members
- Data integrity: Avoid breaking relationships and references
Common scenarios for suspension:
- Employees on leave of absence
- Contractors between engagement periods
- Security incidents requiring immediate access revocation
- Offboarding users while preserving historical context
User Profile Settings
Each user maintains profile information that enhances their experience:
Basic Profile
First name and last name Pulled automatically from your authentication provider (Auth0, etc.). Displayed throughout Catalio for attribution and collaboration.
Email address Your unique identifier across all organizations. Cannot be changed after account creation.
Full name calculation Catalio automatically combines first and last name for display (e.g., “Jessica Martinez”).
Preferences
Preferred language Set your interface language (default: English). Affects:
- UI text and navigation
- AI-generated content where applicable
- Date and number formatting
- Help documentation
Preferred timezone Configure your timezone for accurate timestamp display:
- Requirement creation and update times
- Scheduled reports and notifications
- Audit trail events
- Collaboration timestamps
Provider Metadata
Provider ID Your unique identifier in the authentication system (e.g., Auth0 subject claim
auth0|123456).
Provider data Additional metadata from your authentication provider, including:
- Profile picture URL
- Organization memberships
- Custom attributes from your identity provider
- Authentication metadata
Session Tracking and Security
Catalio tracks authentication activity for security and analytics:
Last Sign-In Timestamp
Records the most recent successful authentication. Helps identify:
- Inactive accounts that may need suspension
- Unusual sign-in patterns
- License usage for billing purposes
Sign-In Count
Tracks the total number of successful authentications. Useful for:
- Understanding user engagement
- Identifying power users vs. occasional users
- Analyzing adoption patterns
Token Management
Catalio uses token-based session management:
- Access tokens: Short-lived tokens (typically 1 hour) for active sessions
- Refresh tokens: Longer-lived tokens for maintaining sessions without re-authentication
- Token storage: All tokens stored securely in the database
- Token revocation: Admins can invalidate sessions immediately by suspending users
When you sign in:
- Authentication provider validates your credentials
- Provider returns identity information and tokens
- Catalio creates a session with stored tokens
- Tokens are used to authorize all subsequent requests
- Expired tokens trigger automatic re-authentication
Multi-Organization Support
While Catalio fully supports multi-organization architecture, each user currently belongs to exactly one organization at a time.
Organization Isolation
Data separation:
- Users in Organization A cannot see any data from Organization B
- OAuth2 tokens respect organization boundaries
- Search and filtering are automatically scoped to your organization
- Audit trails track activity within your organization only
Permission scope:
- Your role applies within your organization only
- Admin access in Organization A does not grant access to Organization B
- Organization membership is determined by your authentication provider
How Organization Assignment Works
When you sign in via Auth0:
- Catalio queries Auth0 for your organization memberships
- Your first organization membership becomes your Catalio organization
- Your role is read from Auth0 organization metadata
- All your activity is scoped to that organization
Changing organizations: Contact your administrator to update your Auth0 organization membership. Changes sync automatically on your next sign-in.
Future Multi-Organization Access
Catalio’s architecture is designed to support users belonging to multiple organizations simultaneously. This would enable:
- Consultants working across multiple client organizations
- Internal users with cross-divisional access
- Organization-switching in the UI
- Per-organization role assignment
Best Practices for User Management
Role Assignment Strategy
Start restrictive, expand as needed:
- Default new users to Contributor or Viewer
- Grant Editor to proven requirement owners
- Limit Admin to 2-3 key stakeholders
- Regularly audit role assignments
Align roles with responsibilities:
- Viewers: Stakeholders, clients, executives, compliance auditors
- Contributors: Individual contributors, domain experts, developers
- Editors: Product managers, business analysts, requirement owners
- Admins: Product leadership, system administrators
Avoid role inflation: Don’t grant Admin just because someone “might need it someday.” Roles can be elevated quickly when necessary.
Security Guidelines
OAuth2 Token Security:
- Tokens are short-lived and automatically refreshed
- MCP clients authenticate via Auth0 OAuth2 flow
- Token revocation occurs automatically when accounts are suspended
- Never share authentication credentials across users
- Monitor MCP access through audit logs
Access Review Cadence:
- Monthly: Review suspended accounts for deletion
- Quarterly: Audit Admin and Editor role assignments
- Annually: Verify all active users still require access
- Immediately: Suspend departing employees before their last day
Authentication Best Practices:
- Require multi-factor authentication (MFA) via Auth0
- Use SSO integration with corporate identity providers
- Monitor last sign-in timestamps for inactive accounts
- Review sign-in counts to identify anomalies
Onboarding New Users
Preparation:
- Determine appropriate role based on responsibilities
- Add user to Auth0 organization with correct metadata
- Prepare onboarding materials specific to their role
First-day checklist:
- Verify user can sign in successfully
- Confirm role permissions are correct
- Introduce them to relevant projects and components
- Provide role-specific training materials
- Set expectations for requirement quality standards
Role-specific onboarding:
- Viewers: Tour of navigation, search, and export features
- Contributors: Requirement writing workshop, AI feature overview
- Editors: Workflow management, approval processes, reporting
- Admins: User management, organization settings, security policies
Offboarding Users
Immediate actions:
- Suspend the user account (don’t delete)
- Revoke all active API keys
- Document any in-progress work needing reassignment
- Transfer ownership of critical requirements if needed
30-day review:
- Verify no access attempts occurred
- Confirm all work has been transferred
- Document any security incidents
90-day retention:
- Maintain suspended status for audit purposes
- Archive account after retention period if no compliance requirements
Never delete users immediately. Deletion removes audit trails and breaks attribution on historical requirements.
Common User Management Scenarios
Scenario 1: Adding a New Product Manager
Goal: Give full editorial control over requirements
Steps:
- Add user to Auth0 organization with
role: editormetadata - User signs in to Catalio via Auth0
- Catalio creates account with Editor role automatically
- User can immediately create, edit, and manage all requirements
Scenario 2: External Stakeholder Review Access
Goal: Allow client to review requirements without edit access
Steps:
- Add stakeholder to Auth0 organization with
role: viewermetadata - Stakeholder signs in and sees read-only view
- Stakeholder can export requirements for offline review
- When engagement ends, suspend the account to revoke access
Scenario 3: AI Agent Integration
Goal: Enable Claude Desktop to access requirements for analysis
Steps:
- Configure Claude Desktop to connect to Catalio’s MCP endpoint
- When Claude attempts access, user is prompted to sign in via Auth0
- Complete OAuth2 authentication in browser
- Claude receives access token and can query requirements
- Agent inherits user’s role permissions automatically
- Tokens auto-refresh - no manual key management required
Scenario 4: Departing Team Member
Goal: Preserve audit trail while revoking access
Steps:
- Suspend user account immediately
- OAuth2 tokens are automatically invalidated
- Review user’s recent contributions
- Reassign in-progress work to other team members
- Maintain suspended status for compliance retention period
Scenario 5: Role Promotion
Goal: Promote high-performing Contributor to Editor
Steps:
- Admin updates user’s role in Auth0 organization metadata
- User signs out and back in to refresh token
- New permissions take effect immediately
- User can now edit all requirements, not just their own
Troubleshooting Common Issues
“I can’t sign in”
Possible causes:
- Account is suspended (contact Admin)
- Wrong authentication provider selected
- Auth0 organization membership missing
- Browser blocking third-party cookies
Resolution:
- Verify account status with Admin
- Check Auth0 organization membership
- Clear browser cache and cookies
- Try incognito/private browsing mode
“I can’t edit a requirement”
Possible causes:
- You have Viewer or Contributor role (need Editor)
- Requirement created by another user (Contributors can only edit their own)
- Requirement is archived
Resolution:
- Check your role in Profile settings
- Request role elevation from Admin if needed
- Ask requirement owner to make changes if you’re a Contributor
“My MCP connection isn’t working”
Possible causes:
- OAuth2 token expired (will auto-refresh)
- User account suspended
- MCP client not configured correctly
- Network connectivity issues
Resolution:
- Try reconnecting - tokens should refresh automatically
- Verify your account is Active in Catalio settings
- Check MCP client configuration points to correct endpoint
- Re-authenticate via Auth0 if prompted
“Role changes aren’t taking effect”
Cause: User’s authentication token contains old role information.
Resolution:
- Sign out completely
- Sign back in to get fresh token
- Verify new role in Profile settings
Next Steps
Now that you understand user management:
- Learn about Organizations - Understand workspace structure and multi-tenancy
- Explore Requirements - See how users create and manage requirements
- API Authentication - Learn about OAuth 2.0, JWT tokens, and API security
Pro Tip: Assign the minimum role needed for each user’s responsibilities. You can always elevate permissions later, but starting restrictive ensures better security and clearer expectations about who manages content.
Support
Questions about user management? We’re here to help:
- Documentation: Continue reading about Organizations and Authentication
- In-App Help: Navigate to Profile → Help for contextual guidance
- Email: support@catalio.ai
- Admin Portal: Admins can access detailed logs at Settings → Audit Trail