Managing Team Members: Users and Roles

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, Clerk, or MCP API keys)
• 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

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:

1. They’re redirected to your organization’s Auth0 tenant
2. They authenticate using configured identity providers (Google, Microsoft, Okta, etc.)
3. Auth0 returns user profile information and organization membership
4. 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 API Keys (Programmatic Access)

For AI agents and automation

MCP (Model Context Protocol) API keys enable programmatic access for:

• AI agents like Claude Desktop
• CI/CD pipelines and automation scripts
• Custom integrations with external tools
• Headless requirement management workflows

How API keys work:

1. Users generate API keys from their profile settings
2. Each key has a unique identifier and expiration date
3. Keys can be named for organization (e.g., “Claude Desktop - Work Laptop”)
4. Keys inherit the creating user’s role and organization access
5. Last usage is tracked for security auditing

Security considerations:

• API keys are shown only once at creation time
• Keys are stored as SHA-256 hashes in the database
• Keys can be revoked immediately if compromised
• Expired keys are automatically invalidated
• Each key has a configurable expiration date (default: 90 days)

Example use case:

A business analyst generates an MCP API key for Claude Desktop. The AI agent can now 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 API keys for programmatic access
• 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 API keys
• 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:

1. Authentication provider validates your credentials
2. Provider returns identity information and tokens
3. Catalio creates a session with stored tokens
4. Tokens are used to authorize all subsequent requests
5. 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
• API keys 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:

1. Catalio queries Auth0 for your organization memberships
2. Your first organization membership becomes your Catalio organization
3. Your role is read from Auth0 organization metadata
4. 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:

1. Default new users to Contributor or Viewer
2. Grant Editor to proven requirement owners
3. Limit Admin to 2-3 key stakeholders
4. 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

API Key Management:

• Set expiration dates appropriate to use case (30-90 days)
• Name keys descriptively (“Claude Desktop - MacBook Pro”)
• Revoke unused or suspicious keys immediately
• Rotate keys periodically for high-security environments
• Never share API keys across users

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:

1. Determine appropriate role based on responsibilities
2. Add user to Auth0 organization with correct metadata
3. Prepare onboarding materials specific to their role

First-day checklist:

1. Verify user can sign in successfully
2. Confirm role permissions are correct
3. Introduce them to relevant projects and components
4. Provide role-specific training materials
5. 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:

1. Suspend the user account (don’t delete)
2. Revoke all active API keys
3. Document any in-progress work needing reassignment
4. 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:

1. Add user to Auth0 organization with role: editor metadata
2. User signs in to Catalio via Auth0
3. Catalio creates account with Editor role automatically
4. 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:

1. Add stakeholder to Auth0 organization with role: viewer metadata
2. Stakeholder signs in and sees read-only view
3. Stakeholder can export requirements for offline review
4. When engagement ends, suspend the account to revoke access

Scenario 3: AI Agent Integration

Goal: Enable Claude Desktop to access requirements for analysis

Steps:

1. User navigates to Profile → API Keys
2. Generate new key: “Claude Desktop - Work Laptop”
3. Set expiration to 90 days
4. Copy plaintext key (shown only once)
5. Configure Claude Desktop with API key
6. Agent can now query requirements using user’s permissions

Scenario 4: Departing Team Member

Goal: Preserve audit trail while revoking access

Steps:

1. Suspend user account immediately
2. Revoke all API keys
3. Review user’s recent contributions
4. Reassign in-progress work to other team members
5. Maintain suspended status for compliance retention period

Scenario 5: Role Promotion

Goal: Promote high-performing Contributor to Editor

Steps:

1. Admin updates user’s role in Auth0 organization metadata
2. User signs out and back in to refresh token
3. New permissions take effect immediately
4. 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:

1. Verify account status with Admin
2. Check Auth0 organization membership
3. Clear browser cache and cookies
4. 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:

1. Check your role in Profile settings
2. Request role elevation from Admin if needed
3. Ask requirement owner to make changes if you’re a Contributor

“My API key isn’t working”

Possible causes:

• Key expired
• Key was revoked
• Key not properly configured in client
• User account suspended

Resolution:

1. Check key expiration date in Profile → API Keys
2. Verify key is still listed as valid
3. Generate new key if expired or revoked
4. Confirm account is Active status

“Role changes aren’t taking effect”

Cause: User’s authentication token contains old role information.

Resolution:

1. Sign out completely
2. Sign back in to get fresh token
3. 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.com
• Admin Portal: Admins can access detailed logs at Settings → Audit Trail