Manage users, roles, and permissions

LinkMesh controls who can do what through role-based access control. A permission is a single capability (read a collector, deploy a pipeline, manage users). A role bundles permissions. A user holds one or more roles, and a role can optionally be scoped to a single collector group. Every action below is also a REST endpoint — see the API reference.

Roles and permissions

Open Roles to see every role and the permissions it carries. Four roles ship built-in:

Role	Access
Admin	Full access to all resources and settings, including user management.
Operator	Monitor the fleet, manage collectors, run commands. Cannot modify pipelines or routing.
Pipeline Engineer	Create, edit, and deploy pipelines. Read-only for collectors and routing.
Viewer	Read-only access to all sections — no create, edit, delete, or deploy.

The Roles page. Each role lists its permission count and a one-line summary; built-in roles are marked and cannot be deleted.

Custom roles

If the built-in roles don’t fit, click + Create Role. Give it a name and description, then select the exact permissions it should carry from the grouped permission picker. Custom roles behave like built-in ones everywhere a role is referenced — user assignments, claim mappings, and scoped grants.

Tip

Start from the closest built-in role’s permission set and add or remove from there. A role with a focused permission set is easier to reason about than one assembled from scratch.

Users

Open Users to manage local accounts. Two ways to add one:

• + Create user (with password) — sets an initial password you share with the user directly.
• Invite user — sends an enrollment link the user completes themselves by setting their own password.

User management. Each user shows its assigned role(s) and join date; the row actions edit the user, reset the password, or remove the account.

Assigning roles

Edit a user to change which roles they hold. A user can hold more than one role — their effective permissions are the union of every role they carry. This lets you compose access (for example, Viewer across the fleet plus Pipeline Engineer for pipeline work) without minting a bespoke role for every combination.

Scope a role to a collector group

A role normally applies fleet-wide. To grant someone a role over just one slice of the fleet, create a scoped role assignment: it binds a user and a role to a single collector group. The user gets that role’s permissions only for collectors in that group, and nothing elsewhere.

Scoped assignments are additive — they grant access on top of whatever fleet-wide roles the user already holds, never subtract from it. Use them to hand a team operational control of their own collectors without giving them the run of every other team’s.

Map identity-provider claims to roles

If you sign in through an external identity provider (OIDC), you can assign roles automatically from the claims your IdP sends — see Configure OIDC single sign-on for connecting one in the first place. Under Roles → claim mappings, map a claim value (typically a group name) to a LinkMesh role. Users who authenticate with that claim receive the mapped role on every login — no manual assignment, and access follows your IdP’s group membership.

A mapping carries four things: the claim path (groups, or a dotted path such as account.roles to walk a nested object), the value to match, the role to grant, and a priority that decides the winner when more than one rule matches. Matching works on a string claim or on any entry of a list claim.

Note

Claim mappings only apply to users who sign in through the configured identity provider. Local password accounts keep the roles you assign them directly.

The mapping wins on every login

An external user’s role is resolved from their claims each time they sign in and overwrites whatever is stored. Editing such a user on the Users page holds only until their next login — change the mapping, or the group membership at your provider, instead.

What’s next

• Configure OIDC single sign-on — connect an identity provider so these mappings have claims to act on
• Authenticate with a service account — non-interactive API access with its own scoped permissions
• Collector groups — the unit a scoped role binds to
• API reference — every user, role, and assignment operation as a REST endpoint