Roles and Permissions

LoopCLI uses a two-tier permission system to control access and capabilities:

1. User Roles - Platform-level roles that control access to administrative features
2. Organization Roles - Team-level roles that control access to projects, loops, and secrets within an organization

User Roles (Platform-Level)

User roles control access to platform-wide administrative features. These are assigned at the account level.

Available User Roles

User (Default)

• Default role for all new accounts
• Full access to their own organizations and projects
• Can create and manage loops
• Can use the CLI and dashboard
• Cannot access admin-only features

Permissions:

• ✅ Create and manage personal projects
• ✅ Join organizations as invited
• ✅ Deploy and run loops
• ✅ Access vault secrets (based on organization role)
• ❌ No access to admin endpoints
• ❌ Cannot re-key vault encryption

Staff

• Platform support team members
• Additional monitoring and diagnostic capabilities
• Can assist users with technical issues

Permissions:

• ✅ All User permissions
• ✅ Access to support tools
• ✅ View aggregate platform metrics
• ❌ Cannot perform admin-level operations

Admin

• Platform administrators
• Full system access and control
• Can perform sensitive operations like vault re-keying

Permissions:

• ✅ All User and Staff permissions
• ✅ Trigger vault re-encryption
• ✅ Access internal admin endpoints
• ✅ Manage platform-wide settings

Organization Roles (Team-Level)

Organization roles control what team members can do within a specific organization. Each user can have different roles in different organizations.

Available Organization Roles

Viewer

Read-only access - Perfect for stakeholders who need visibility without making changes

Permissions:

• ✅ View organization details
• ✅ View all projects in the organization
• ✅ View loops and execution history
• ✅ View logs and analytics
• ✅ View (but not reveal) secret names in vault
• ❌ Cannot create or modify projects
• ❌ Cannot deploy or run loops
• ❌ Cannot access secret values
• ❌ Cannot invite team members

Use cases:

• Product managers reviewing automation workflows
• Executives monitoring operational metrics
• External auditors or consultants

Runner

Execute-only access - Can trigger automations but not change them

Permissions:

• ✅ All Viewer permissions
• ✅ Manually trigger loop execution
• ✅ Run loops from CLI
• ✅ View secret values (read-only)
• ❌ Cannot create or edit loops
• ❌ Cannot modify projects or settings
• ❌ Cannot create or update secrets
• ❌ Cannot invite team members

Use cases:

• Operations team members who run scheduled tasks
• Customer support triggering workflows
• CI/CD systems with limited scope

Manager

Full project control - Can create and manage all automation resources

Permissions:

• ✅ All Viewer and Runner permissions
• ✅ Create and delete projects
• ✅ Create, edit, and deploy loops
• ✅ Manage loop schedules
• ✅ Create, update, and delete vault secrets
• ✅ Invite new organization members
• ✅ Change roles of Viewers and Runners
• ❌ Cannot delete the organization
• ❌ Cannot remove or demote owners

Use cases:

• Engineering team leads
• DevOps engineers
• Automation developers

Owner

Full organization control - Complete administrative access

Permissions:

• ✅ All Manager permissions
• ✅ Modify organization settings
• ✅ Delete the organization
• ✅ Remove any team member (including other owners)
• ✅ Change any member's role
• ✅ Transfer billing ownership

Use cases:

• Organization creators
• C-level executives
• Account administrators

Permission Matrix

Managing Team Members

Inviting Users to Your Organization

From the Dashboard:

1. Navigate to your organization settings
2. Go to the "Team" tab
3. Click "Invite Member"
4. Enter their email address and select a role
5. Send the invitation

From the CLI:

# Invite a team member as a Manager
loopcli team invite user@example.com --role manager

# Invite as Viewer (read-only)
loopcli team invite user@example.com --role viewer

Changing Member Roles

From the Dashboard:

1. Go to Team settings
2. Find the member in the list
3. Click the role dropdown next to their name
4. Select the new role

From the CLI:

# Promote a user to Manager
loopcli team set-role user@example.com manager

# Demote a user to Viewer
loopcli team set-role user@example.com viewer

Restrictions:

• Only Managers and Owners can change roles
• Managers can only modify Viewer and Runner roles
• Owners can modify any role, including other Owners

Removing Team Members

From the Dashboard:

1. Go to Team settings
2. Find the member in the list
3. Click "Remove" next to their name
4. Confirm the removal

From the CLI:

# Remove a team member
loopcli team remove user@example.com

Restrictions:

• Only Managers and Owners can remove members
• Managers cannot remove Owners
• You cannot remove yourself (transfer ownership first)

Best Practices

Role Assignment Strategy

Start with least privilege:

• Default to Viewer for new team members
• Promote to Runner when they need to execute workflows
• Elevate to Manager only when they need to create/modify

Use Runners for automation:

• CI/CD pipelines should use Runner tokens
• Scheduled jobs don't need Manager permissions
• Reduces risk if credentials are compromised

Limit Owner count:

• Keep 2-3 Owners maximum
• More Owners = higher risk of accidental deletions
• Document who the Owners are

Security Recommendations

Audit team access regularly:

# List all organization members
loopcli team list

# Review who has Manager/Owner access
loopcli team list --role owner,manager

Rotate secrets when people leave:

• When a team member leaves, rotate vault secrets they accessed
• Review which projects they had access to
• Audit recent loop executions

Use separate organizations for different environments:

# Production organization (limited access)
loopcli org switch acme-prod

# Development organization (wider access)
loopcli org switch acme-dev

Monitor organization activity:

• Check vault activity logs regularly
• Review loop execution history
• Watch for unexpected deployments

Common Scenarios

Scenario 1: Onboarding a Developer

# 1. Invite as Viewer first
loopcli team invite dev@company.com --role viewer

# 2. After orientation, promote to Runner
loopcli team set-role dev@company.com runner

# 3. When ready to build automations, promote to Manager
loopcli team set-role dev@company.com manager

Scenario 2: External Consultant Access

# Give read-only access to consultant
loopcli team invite consultant@agency.com --role viewer

# When project ends, remove access
loopcli team remove consultant@agency.com

Scenario 3: CI/CD Integration

# Create a Runner API key for deployment pipeline
loopcli auth create-api-key --name "GitHub Actions" --org-role runner

# Use in CI with limited permissions (can run, cannot modify)

Scenario 4: Setting up Support Team

# Support team needs to trigger workflows but not change them
loopcli team invite support1@company.com --role runner
loopcli team invite support2@company.com --role runner

Troubleshooting

"Permission Denied" Errors

When deploying a loop:

Error: Permission denied. Manager role required.

→ You need Manager or Owner role in this organization

When viewing secrets:

Error: Cannot access secret values.

→ You need at least Runner role to view secret values

When inviting team members:

Error: Insufficient permissions to modify team.

→ You need Manager or Owner role to invite members

Checking Your Permissions

# View your current role in active organization
loopcli auth whoami

# List all organizations and your roles
loopcli org list

# Switch to different organization
loopcli org switch <org-name>

Related Documentation

• Organizations and Teams
• CLI Command Reference
• Vault Secrets Management
• Security Best Practices

Support

Questions about roles and permissions?

• Discord: Join our community
• Need help? Use the contact form or post in Discord
• Docs: https://docs.loopcli.com