fetch_ml/docs/src/user-permissions.md

User Permissions in Fetch ML

Fetch ML now supports user-based permissions to ensure data scientists can only view and manage their own experiments while administrators retain full control.

Overview

• User Isolation: Each user can only see their own experiments
• Admin Override: Administrators can view and manage all experiments
• Permission-Based: Fine-grained permissions for create, read, update operations
• API Key Authentication: Secure authentication using API keys

Permissions

Job Permissions

• jobs:create - Create new experiments
• jobs:read - View experiment status and results
• jobs:update - Cancel or modify experiments

User Types

• Administrators: Full access to all experiments and system operations
• Data Scientists: Access to their own experiments only
• Viewers: Read-only access to their own experiments

CLI Usage

View Your Jobs

ml status

Shows only your experiments with user context displayed.

Cancel Your Jobs

ml cancel <job-name>

Only allows canceling your own experiments (unless you're an admin).

Authentication

The CLI automatically authenticates using your API key from ~/.ml/config.toml.

Configuration

API Key Setup

[worker]
api_key = "your-api-key-here"

User Roles

User roles and permissions are configured on the server side by administrators.

Security Features

• API Key Hashing: Keys are hashed before transmission
• User Filtering: Server-side filtering prevents unauthorized access
• Permission Validation: All operations require appropriate permissions
• Audit Logging: All user actions are logged

Examples

Data Scientist Workflow

# Submit your experiment
ml queue my-experiment

# Check your experiments (only shows yours)
ml status

# Cancel your own experiment
ml cancel my-experiment

# Requeue a previous run with different args
ml requeue <run_id|task_id|path> -- --epochs 20

Administrator Workflow

# View all experiments (admin sees everything)
ml status

# Cancel any user's experiment
ml cancel user-experiment

Error Messages

• "Insufficient permissions": You don't have the required permission
• "You can only cancel your own jobs": Ownership restriction
• "Invalid API key": Authentication failed

Migration Notes

• Existing configurations continue to work
• When auth is disabled, all users have admin-like access
• User ownership is automatically assigned to new experiments

For more details, see the architecture documentation.