Skip to content

Roles & Permissions

Understand how Preloop's Role-Based Access Control (RBAC) system works and how to manage user permissions.

Overview

Preloop uses Role-Based Access Control (RBAC) to manage what users can do in your account. Every user is assigned one or more roles, and each role grants a specific set of permissions.

Key concepts:

  • Permissions - Atomic units of access (e.g., "manage_users", "create_flows")
  • Roles - Collections of permissions (e.g., "Admin" has many permissions)
  • Users - Assigned roles that determine their access level
  • Teams - Groups of users that can inherit roles

Benefits:

  • Fine-grained access control
  • Principle of least privilege
  • Easy permission management
  • Audit trail of role changes

System Roles

Preloop provides 7 system roles that cover common access patterns. These roles are available to all accounts and cannot be modified.

1. Owner

Full account access including billing and account management.

Permissions:

  • All permissions from Admin role
  • Manage billing and subscription
  • Close/delete account
  • Transfer account ownership
  • View all audit logs

Use cases:

  • Account creator (automatically assigned)
  • Primary decision maker
  • Billing contact

Who should have this:

  • Company founder or C-level executive
  • Person responsible for payment
  • Limit to 1-2 users for security

2. Admin

Full access except billing and account closure.

Permissions:

  • Manage users (invite, remove, change roles)
  • Manage teams
  • Manage all tools and MCP servers
  • Create and manage approval workflows
  • Create and manage flows
  • Manage trackers (GitHub, GitLab, Jira)
  • View all projects and activity
  • Approve any approval request
  • View audit logs

Cannot:

  • Manage billing/subscription
  • Close/delete account
  • Transfer ownership

Use cases:

  • Engineering managers
  • DevOps leads
  • Platform administrators

Who should have this:

  • Technical leaders who need full control
  • Users managing the platform day-to-day
  • Typically 2-5 users

3. Editor

Configure the control plane: agents, tools, policies, models, flows, and trackers.

Permissions:

  • Create and edit flows, tools, policies, and approval workflows
  • Manage MCP servers and AI models
  • Manage agents and runtime sessions
  • Connect trackers and projects
  • View cost analytics
  • Decide approval requests and control managed agents

Cannot:

  • Manage users, teams, or invitations
  • Manage billing or close the account
  • Manage budget policies

Use cases:

  • Senior engineers
  • Technical product managers
  • Automation / platform engineers

Who should have this:

  • Users building and governing automations
  • Users configuring MCP firewall policies
  • Typically 5-15 users

4. Executor

Operate day-to-day: execute flows, decide approvals, and control agents.

Permissions:

  • Execute existing flows and use tools
  • View and decide approval requests
  • View agents, sessions, models, and cost
  • Control managed agents
  • Create/comment issues

Cannot:

  • Create or edit flows, tools, policies, or models
  • Add MCP servers or trackers
  • Manage users, teams, or billing

Use cases:

  • Junior engineers
  • Operations team members
  • Support engineers

Who should have this:

  • Users who run existing automations and handle approvals
  • Users who talk to managed agents without changing config
  • Most common role - typically 20-50% of users

5. Tracker Manager

Manage issue trackers and sync data.

Permissions:

  • Add and remove trackers (GitHub, GitLab, Jira)
  • Configure tracker settings
  • Force sync tracker data
  • View tracker connection status
  • View issues and projects

Cannot:

  • Create flows
  • Manage tools
  • Manage users
  • Access approval workflows

Use cases:

  • Engineering managers (focused on project management)
  • Scrum masters
  • Project managers

Who should have this:

  • Users responsible for issue tracking
  • Users managing project data
  • Typically 2-5 users

6. Analyst

Read-only access plus compliance, cost, and audit insights.

Permissions:

  • View flows, tools, policies, MCP servers, agents, sessions, and models
  • View cost analytics and audit logs
  • Run compliance checks
  • Detect duplicate issues and manage dependencies

Cannot:

  • Create or modify control-plane configuration
  • Execute flows or decide approvals
  • Control managed agents
  • Manage users, teams, or billing

Use cases:

  • Compliance officers
  • Security auditors
  • Business analysts
  • Stakeholders who need visibility

Who should have this:

  • Users who need to monitor and analyze
  • Non-technical stakeholders
  • Typically 5-10 users

7. Viewer

Read-only access to core control-plane resources.

Permissions:

  • View flows, tools, policies, MCP servers, trackers, projects, issues
  • View models, agents, sessions, and compliance results

Cannot:

  • View cost, audit logs, or approvals
  • Execute, configure, or decide anything

Use cases:

  • External consultants
  • Temporary contractors
  • Demo accounts

Who should have this:

  • Users who just need visibility
  • External parties with limited access
  • Use sparingly - prefer Analyst for internal users

Role Comparison Matrix

Capability Owner Admin Editor Executor Tracker Mgr Analyst Viewer
Manage users / teams / invites ✅ ✅ ❌ ❌ ❌ ❌ ❌
Manage billing / close account ✅ ❌ ❌ ❌ ❌ ❌ ❌
Configure agents / tools / policies / models ✅ ✅ ✅ ❌ ❌ ❌ ❌
Control managed agents ✅ ✅ ✅ ✅ ❌ ❌ ❌
Execute flows / decide approvals ✅ ✅ ✅ ✅ ❌ ❌ ❌
View cost analytics ✅ ✅ ✅ ✅ ❌ ✅ ❌
Manage budgets ✅ ✅ ❌ ❌ ❌ ❌ ❌
Manage trackers / projects / issues ✅ ✅ ✅ limited ✅ ❌ ❌
Run compliance / duplicates / deps ✅ ✅ ✅ ❌ ❌ ✅ ❌
View audit logs ✅ ✅ ❌ ❌ ❌ ✅ ❌
Read-only core resources ✅ ✅ ✅ ✅ partial ✅ ✅

Permission names use verb_resource underscores (for example view_cost, decide_approvals, create_projects). Re-run python scripts/init_system_roles.py after upgrades to reconcile system roles on existing deployments.

Notes:

  • Owner bypasses explicit permission rows and is treated as having every permission.
  • Executor can create/comment issues and view sessions/cost, but cannot change tool/policy/model configuration.
  • Tracker Manager is specialized for tracker/project/org/issue data and does not manage the agent control plane.
  • Analyst is read-heavy plus compliance/cost/audit analysis; it cannot mutate control-plane config or decide approvals.

Managing User Roles

Adding a New User

  1. Go to Settings → Users
  2. Click + Invite User
  3. Fill in the form: 
    Email: alice@acme.com
Role: Editor
Teams: [Optional - add to teams]
Send invitation email: ✅
  4. Click Send Invitation

What happens:

  • Invitation email sent to user
  • User clicks link and creates account
  • User automatically added with specified role
  • User appears in Users list

Changing a User's Role

  1. Go to Settings → Users
  2. Find the user
  3. Click Edit (pencil icon)
  4. Select new role from dropdown: 
    Current Role: Executor
New Role: Editor
  5. Click Save

Important notes:

  • Changes take effect immediately
  • User doesn't need to log out/in
  • Previous permissions removed
  • New permissions granted
  • Role change logged in audit trail

Who can change roles:

  • Owner can change anyone's role
  • Admin can change roles except Owner
  • No one else can change roles

Removing a User

  1. Go to Settings → Users
  2. Find the user
  3. Click Remove (trash icon)
  4. Confirm removal

What happens:

  • User immediately loses access
  • User's API keys revoked
  • User's pending approval requests remain (reassigned to Admin)
  • User's created flows remain (ownership transferred to Admin)
  • Audit logs retained

Who can remove users:

  • Owner can remove anyone
  • Admin can remove anyone except Owner
  • No one else can remove users

Custom Roles

Enterprise Feature - Custom roles allow you to create your own roles with specific permissions tailored to your organization.

Creating a Custom Role

  1. Go to Settings → Roles
  2. Click + Create Custom Role

  3. Fill in the form: 

    Name: Deployment Manager
Description: Can manage deployment flows and approve production deploys
Based on: Editor (start with Editor permissions)

  4. Customize permissions: 

    ✅ Create flows
✅ Edit flows
✅ Execute flows
✅ Approve requests (for deployment tools)
❌ Add MCP servers (remove this)
❌ Manage trackers (remove this)

  5. Click Create

Use cases:

  • Deployment Manager - Focused on deployment flows only
  • Support Engineer - Execute flows + view issues, but no edits
  • Compliance Reviewer - Analyst + approval power for specific tools
  • External Consultant - Viewer + execute specific flows

Team Roles

Teams can be assigned roles, granting all team members those permissions.

How Team Roles Work

Scenario:

  • Team: "SRE Team"
  • Members: Alice, Bob, Charlie
  • Team Role: Editor

Result:

  • Alice has Editor permissions
  • Bob has Editor permissions
  • Charlie has Editor permissions

If Bob is also individually assigned Admin:

  • Bob has Admin permissions (highest role wins)

Assigning a Role to a Team

  1. Go to Settings → Teams
  2. Find the team
  3. Click Edit
  4. Assign role: 
    Team: SRE Team
Role: Editor
  5. Click Save

All team members immediately get Editor permissions.

Permission Hierarchies

Role Hierarchy

Roles are hierarchical for role management purposes:

Owner (highest)
  ↓
Admin
  ↓
Editor
  ↓
Executor
  ↓
Tracker Manager
  ↓
Analyst
  ↓
Viewer (lowest)

Rules:

  • Owner can manage all roles
  • Admin can manage all roles except Owner
  • Others cannot manage roles

Permission Combination

If a user has multiple roles (individual + team):

Example:

  • Individual role: Executor
  • Team role: Editor
  • Effective permissions: Editor (highest wins)

Rule: User gets the union of all permissions from all roles.

Approval Permissions

Who Can Approve Requests?

Any role can approve IF:

  1. They're listed as approver in the tool's approval workflow
  2. OR they're in a team that's listed as approver
  3. OR the policy says "Any Admin/Owner"

Example:

Tool: deploy_production
Approvers: [sre_team, cto@acme.com]

Can approve: - ✅ Members of sre_team (any role) - ✅ cto@acme.com (any role) - ❌ Other users (even if Admin)

Exception:

  • Owner and Admin can override and approve any request in emergency situations

Delegation

Users can temporarily delegate their approval authority:

  1. Go to Settings → Delegations
  2. Click + Add Delegation
  3. Configure: 
    Delegate to: bob@acme.com
Start: 2025-01-25
End: 2025-02-01
Tools: All (or specific tools)
  4. Click Create

Result:

  • Approval requests go to Bob instead of you
  • Bob approves on your behalf
  • Audit log shows delegation

Audit Trail

Viewing Role Changes

  1. Go to Settings → Audit Logs
  2. Filter by category: "User Management"
  3. See events:
  4. User invited
  5. User role changed
  6. User removed
  7. Team role changed

Each entry shows:

  • Who made the change
  • What changed (old role → new role)
  • When it happened
  • IP address

Compliance Reports

Enterprise Feature - Generate compliance reports:

  1. Go to Settings → Reports
  2. Select Access Control Report
  3. Date range: Last 90 days
  4. Click Generate

Report includes:

  • All users and their roles
  • All role changes in period
  • All approval requests and who approved
  • Access violations (if any)

API Access with Roles

API Keys Inherit User Role

When you create an API key: - API key inherits YOUR role - API calls have same permissions as you - Subject to same approval workflows

Example:

If you're an Executor: - API key can execute flows ✅ - API key cannot create flows ❌ - API key cannot add MCP servers ❌

Service Accounts

Enterprise Feature - Create dedicated service accounts for API access:

  1. Go to Settings → Service Accounts
  2. Click + Create Service Account
  3. Configure: 
    Name: CI/CD Pipeline
Role: Executor
Description: For automated deployments
  4. Click Create
  5. Copy API key

Benefits:

  • Separate from human users
  • Can be rotated without affecting user
  • Clear audit trail
  • Can be disabled independently