Roles & permissions

Give teammates exactly the access they need with capability-based roles.

The dashboard uses capability-based access control: every user has one role, and a role grants capabilities as a grid of section × action (view / edit). Manage it all under Settings → Roles and Settings → Users.

How access works

Access is decided by three things:

  1. Role — a named bundle of capabilities. Each user holds exactly one.
  2. Section — an area of config: Global, Service Groups, Tags, Pauses, Blocks, Scripts, Protobuf Schemas, Snapshots, Push, Stats, Status, Users, TestFlight, Devices.
  3. Action — view (read the section) or edit (change it). edit implies view.
UserRoleSection: viewSection: editSection: —

Enforcement is server-side: every read and write is gated by Postgres Row-Level Security calling has_capability(section, action). The UI also hides sections you can't view, but that sits on top of real backend enforcement — hitting the API directly still goes through RLS.

Built-in roles

Two roles ship with the dashboard and cover most needs:

RoleAccessNotes
adminFull view + edit on every section (grants all)Protected — can't be edited or deleted.
viewerTheir own devices + captured traffic onlyThe default for new users. No fleet config.

A viewer can sign in, manage their own devices, read their own traffic, and use the per-user reference pages — but sees none of the fleet-wide configuration sections.

Custom roles

Admins build roles tailored to a team under Settings → Roles.

  1. Click New role and name it.
  2. Toggle view / edit per section — one row per section, a checkbox per action:
SectionCovers
GlobalGlobal settings + environment (inspect/MITM flags, connection defaults, DNS, external proxy, maintenance).
Service GroupsSSL-proxy domain bundles.
TagsColored URL-pattern labels.
PausesPassthrough hosts.
BlocksAuto-block / drop / mock rules (block rules).
ScriptsRequest/response JavaScript hooks (scripting) — view to read; edit (+ admin + confirm) to write arbitrary code.
Protobuf SchemasUploaded .proto files + host mappings.
SnapshotsProject backups.
PushPush tokens + send-push.
StatsLive capture metrics.
StatusInfrastructure health.
UsersProfiles + role assignment (and the Roles editor itself).
TestFlightBeta testers + groups.
DevicesFleet-wide device list + control.
  1. Save. The role appears immediately and can be assigned.

Editing a role's capabilities takes effect live for everyone who holds it — affected sessions re-evaluate their nav and access on the next push.

Assigning a role

Two equivalent paths:

  • Settings → Users — open a user and pick their role.
  • Settings → Roles — open a role to see and edit its member list.

A user always has exactly one role; changing it re-scopes what they see immediately.

What a minimal role sees

The nav hides any section a role can't view. A role with no fleet capabilities still gets the per-user surfaces, always scoped to that user's own data:

  • Account — profile, password, linked providers.
  • Devices — but only the ones they own.
  • CDP — their own CDP-connector devices.
  • The REST / WebSocket / MCP explorers — read-only, with their own credentials pre-filled.

So even a minimal role is a fully usable account — just without fleet-wide configuration.

The admin role is protected

To stop you locking everyone out:

  • The admin role can't be deleted or edited — its full-access set is fixed.
  • You can't strip admin's capabilities.
  • You can't demote the last admin — there's always at least one.

To hand off, promote another user to admin first, then change your own role.

Troubleshooting

  • A section is missing from the nav — your role lacks view on it; an admin can grant it.
  • A page loads but edits fail (403) — your role has view but not edit; RLS rejects the write.
  • Can't change your own role — by design; another admin must do it.
  • Role change didn't take — capabilities push live; if a stale tab shows old nav, hard-reload it.
Remote settings & envDeveloper consoles