Skip to main content

​
Access Control & User Roles

Comprehensive role-based access control system defining user permissions and security boundaries within ReptiDex vivariums and platform features.

​
Quick Navigation

User Roles
RBAC role definitions
Permissions
Detailed permission matrix
Implementation
Technical implementation
Security Policies
Access control policies

​
User Roles & Hierarchy

​
Vivarium Role-Based Access Control

reptidex uses a role-based access control system with husbandry-themed role names that map to traditional RBAC permissions. Each vivarium (organization) has its own role hierarchy.

Role Philosophy

Husbandry-Themed Naming
  • Role names use reptile care terminology
  • Clear hierarchy from Keeper to Herpetologist
  • Intuitive for reptile breeding community
  • Maps to standard RBAC permissions

Scope & Context

Per-Vivarium Roles
  • Roles are assigned within each vivarium
  • Users can have different roles in different vivariums
  • Personal collections have implicit owner permissions
  • Platform-level admin roles exist separately

​
Role Definitions

  • Keeper (Viewer)
  • Handler (Editor)
  • Curator (Admin)
  • Herpetologist (Owner)

​
Keeper Role - Read-Only Access

RBAC Equivalent: Viewer/Read-OnlyDescription: Entry-level access for assistants, potential buyers, or collaborators who need visibility into the vivarium without modification rights.Permissions:
  • ✅ View animals and their basic information
  • ✅ View pedigrees and lineage information
  • ✅ View clutch records and breeding outcomes
  • ✅ View photos and media
  • ✅ Access care guides and husbandry information
  • ✅ View public marketplace listings from the vivarium
  • ❌ Cannot modify any data
  • ❌ Cannot add or edit animals
  • ❌ Cannot access billing or financial information
  • ❌ Cannot invite other users
Use Cases:
  • Potential buyers evaluating animals
  • Assistant caretakers who only need to view information
  • Students or apprentices learning from experienced breeders
  • Veterinarians who need access to medical history
  • Partner breeders evaluating collaboration opportunities
Security Considerations:
  • Cannot export sensitive data
  • No access to private notes or internal communications
  • Time-limited access can be configured
  • Activity logging for audit purposes

​
Detailed Permissions Matrix

​
Core Platform Permissions

FeatureKeeperHandlerCuratorHerpetologist
View Animals✅✅✅✅
Add/Edit Animals❌✅✅✅
Manage Breeding Records❌✅✅✅
Create Marketplace Listings❌✅✅✅
Invite Team Members❌❌✅✅
Manage Member Roles❌❌⚠️*✅
Access Billing❌❌❌✅
Delete Vivarium❌❌❌✅
⚠️ Curator Limitations: Curators can manage roles for Keepers and Handlers only. They cannot modify other Curator roles or the Herpetologist role.

​
Feature-Specific Permissions

  • Animal Management
  • Breeding Management
  • Marketplace & Commerce
  • Team & Vivarium Management

​
Animal & Collection Management

PermissionKeeperHandlerCuratorHerpetologist
View Animals✅ All public✅ All assigned✅ All vivarium✅ All vivarium
Add Animals❌✅ Standard animals✅ All animals✅ All animals
Edit Basic Info❌✅ Own entries✅ All vivarium✅ All vivarium
Delete Animals❌❌✅ With approval✅ All animals
Transfer Animals❌❌✅ Within vivarium✅ Any transfer
Export Data❌❌✅ Vivarium data✅ All data
View Private Notes❌✅ Own notes✅ All notes✅ All notes
Archive Animals❌✅ Own entries✅ All vivarium✅ All vivarium

​
Technical Implementation

​
Role Assignment & Context

  • Database Schema
  • API Implementation
  • Frontend Integration

​
User Role Data Model

-- Vivarium member roles
CREATE TABLE repti_core.vivarium_members (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    vivarium_id UUID REFERENCES repti_core.vivariums(id) ON DELETE CASCADE,
    user_id UUID REFERENCES repti_core.users(id) ON DELETE CASCADE,
    role vivarium_role_enum NOT NULL,
    permissions JSONB DEFAULT '{}',
    invited_by UUID REFERENCES repti_core.users(id),
    joined_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    UNIQUE(vivarium_id, user_id)
);

-- Role enumeration
CREATE TYPE vivarium_role_enum AS ENUM (
    'keeper',        -- Read-only access
    'handler',       -- Editor permissions
    'curator',       -- Admin permissions
    'herpetologist'  -- Owner permissions
);

-- Permission tracking
CREATE TABLE repti_core.role_permissions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    role vivarium_role_enum NOT NULL,
    resource VARCHAR(50) NOT NULL,
    action VARCHAR(30) NOT NULL,
    allowed BOOLEAN DEFAULT FALSE,
    conditions JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Audit trail for role changes
CREATE TABLE repti_core.role_audit_log (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    vivarium_id UUID NOT NULL,
    target_user_id UUID NOT NULL,
    changed_by_user_id UUID NOT NULL,
    old_role vivarium_role_enum,
    new_role vivarium_role_enum,
    reason TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

​
Security Policies & Best Practices

​
Role Assignment Security

Role Elevation

Promotion Guidelines
  • Curators cannot promote users to Curator level
  • Only Herpetologist can create other Curators
  • Automatic approval workflows for role changes
  • Notification system for role modifications

Access Auditing

Audit Requirements
  • All role changes logged with timestamps
  • Regular access reviews and certifications
  • Automated alerts for suspicious activity
  • Role usage analytics and reporting

​
Security Enforcement

  • Authentication Requirements
  • Session Management
  • Data Access Controls
  • Compliance & Governance

​
Multi-Factor Authentication Policies

Role-Based MFA Requirements:
  • Keeper: Optional MFA (recommended)
  • Handler: Required for financial features
  • Curator: Required MFA for all access
  • Herpetologist: Required MFA + backup codes
Implementation:
async def verify_mfa_requirement(user_role: VivariumRole, action: str) -> bool:
    mfa_required_actions = {
        'handler': ['financial_transaction', 'high_value_animal'],
        'curator': ['*'],  # All actions
        'herpetologist': ['*']  # All actions
    }
    
    if user_role in ['curator', 'herpetologist']:
        return True
        
    if user_role == 'handler' and action in mfa_required_actions['handler']:
        return True
        
    return False
This comprehensive access control system provides reptidex with enterprise-grade security while maintaining intuitive, husbandry-themed role names that resonate with the reptile breeding community. The hierarchical role structure ensures clear permission boundaries while enabling flexible collaboration within vivariums.