Users

Users are the people who access your Catalio workspace. Each user has a defined role that controls their permissions, a sign-in method for 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
• Sign-in method: Catalio authentication (email/password or SSO when enabled for your organization)
• 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 resources they can reach

Organization roles and per-resource sharing work together (see Sharing Overview). Viewers can read resources their grants or internal visibility expose — not every resource in the organization unless they are an organization Admin.

Viewers can:

• ✅ Browse and search requirements, personas, use cases, and test cases they can access
• ✅ 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 edit control over resources they can reach

Editors can modify resources where they hold Editor, Admin, or Owner sharing grants (or where internal visibility plus an edit grant applies). Organization Admins bypass per-resource checks.

Editors can:

• ✅ Create, edit, and delete requirements and related content they can access
• ✅ 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 LLM providers
• ✅ 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 for the organization when enabled, 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.

Sign-In and Authentication

Web and MCP access use your personal Catalio account (Catalio authentication). API integrations use a separate path: organization-scoped OAuth client credentials with the client_credentials grant (Settings → API Credentials). Both belong to the same organization, but they authenticate differently — an API credential is not the same as a user’s sign-in session.

Web Sign-In

When users open Catalio:

1. They sign in with their Catalio account (email and password, or SSO when enabled for your organization)
2. Catalio validates the session and loads organization membership
3. The user’s organization role (Admin, Editor, Contributor, or Viewer) applies for membership administration and baseline access rules
4. Per-resource sharing grants further control what they can see and edit (see Sharing Overview)

Enterprise features when configured:

• Single Sign-On (SSO) and federation with your corporate identity provider
• Multi-factor authentication (MFA) as configured for your organization
• Automatic membership sync when SSO is enabled

Organization administrators assign and change organization roles in Catalio (Settings → Members).

MCP and API Access

MCP (Model Context Protocol) — AI agents such as Claude Desktop and Claude Code connect with Catalio OAuth using the same account as the web app. No separate API key is required.

API credentials — Service-to-service integrations use OAuth client credentials created in Settings → API Credentials. See API Authentication.

See MCP Authentication for step-by-step MCP connection instructions.

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 from your sign-in profile when available. 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

Account identifier Your stable identifier in Catalio’s authentication system.

Profile metadata Additional sign-in metadata when available, 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

A single Catalio user identity can hold memberships across multiple organizations. Each membership carries its own role within that organization, and the user has a single currently active organization that scopes their session.

Organization Isolation

Data separation:

• Users only see data for the organization they are currently active in
• OAuth2 tokens respect organization boundaries
• Search and filtering are automatically scoped to the active organization
• Audit trails track activity within the active organization only

Permission scope:

• Roles are assigned per organization membership — Admin in Organization A does not grant access to Organization B
• Switching organizations changes which role applies to the session
• Each organization’s data, settings, and integrations remain fully isolated

How Organization Membership Works

When you sign in to Catalio:

1. Catalio loads all organization memberships tied to your account
2. A membership record is created or updated for each organization you belong to
3. Your organization role for each membership is applied from Catalio’s membership records
4. One of your memberships is set as the currently active organization for the session

Switching organizations: Users with multiple memberships can switch their active organization in the UI; activity from that point on is scoped to the newly selected organization.

Membership management: Organization administrators invite users and assign roles in Catalio. When SSO is enabled, membership may also sync from your corporate directory on sign-in.

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

OAuth2 Token Security:

• Tokens are short-lived and automatically refreshed
• MCP clients authenticate via Catalio OAuth
• 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) when your organization has it enabled
• 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. Invite the user to your Catalio organization with the correct role
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. Admin invites user to the organization with Editor role
2. User signs in to Catalio
3. User receives Editor permissions on next session
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. Admin invites stakeholder with Viewer role
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. Configure Claude Desktop to connect to Catalio’s MCP endpoint
2. When Claude attempts access, user is prompted to sign in to Catalio
3. Complete OAuth2 authentication in browser
4. Claude receives access token and can query requirements
5. Agent inherits user’s role permissions automatically
6. Tokens auto-refresh - no manual key management required

Scenario 4: Departing Team Member

Goal: Preserve audit trail while revoking access

Steps:

1. Suspend user account immediately
2. OAuth2 tokens are automatically invalidated
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 the user’s organization role in Catalio
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)
• Organization membership missing or invitation not accepted
• Browser blocking third-party cookies

Resolution:

1. Verify account status with Admin
2. Confirm organization membership with your administrator
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 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:

1. Try reconnecting - tokens should refresh automatically
2. Verify your account is Active in Catalio settings
3. Check MCP client configuration points to correct endpoint
4. Re-authenticate on the Catalio sign-in screen if prompted

“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

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