A person’s role reaches Shepherd two ways, and the two coexist. Either your identity provider puts them in a group Shepherd knows about, or an application administrator gives them a local account and a role in an organisation. Neither is a fallback for the other — you can run entirely on single sign-on, entirely on local accounts, or mix them, and a session is judged on one source only.
| Actor | Can | Cannot |
|---|---|---|
| Application administrator | Everything, everywhere: create organisations and set their tenant identity, claim clusters into orgs, issue and revoke agent tokens, configure single sign-on, manage local accounts. | — |
| Organisation administrator | Everything inside one org, including what the org is: destinations, tenant routes, git credentials and repo links, teams, service accounts, the group assignments and labels on that org’s collectors, Connect a cluster, a pipeline’s owning team, and the org’s audit log. | Reach another org, claim clusters, or manage agent tokens. |
| Organisation editor | Author what the org runs: pipelines, wizards, the visual builder, simulations. | Change where telemetry ships — destinations, tenant routes, git credentials and teams stay with the org admin, as do collector labels, a pipeline’s owning team and the audit log. |
| Team member | Edit, enable, disable, restore, detach and delete the pipelines their team owns, as text or in the visual builder; read the rest of the org like a viewer. | Touch pipelines their team does not own, create pipelines in the UI (from a wizard, the visual builder or text), or run a simulation — those stay with the org editor. (Through the API a team member can create a pipeline owned by their own team.) |
| Viewer | View the organisation’s collectors and pipelines, and the config each collector is served. | Create or change anything. |
Service account (apply) |
Machine writes within one org, and every write must name the human it acts for — a claim verified against the credential, not taken on trust. | Ever be an app admin. Act without an on-behalf-of. |
Service account (propose) |
Read, validate and simulate freely. | Apply anything. |
| Collector (agent token) | Fetch its own merged config and report status, over HTTP Basic auth with an agent token, or with an OIDC access token. | Read or change anything in the management API. |
Writing a pipeline and re-pointing where an org’s telemetry ships used to be the same permission: both needed org admin. They are different risks. An editor can author freely without being able to change a destination, a tenant route, or a git credential — so the person who tunes a scrape interval does not also hold the ability to redirect the fleet’s data somewhere else.
From your identity provider. Each organisation names an admin, editor and
viewer group at Admin → Organisations. Whatever your provider emits in the groups
claim is matched against those values — object GUIDs for Microsoft Entra, and for every
other provider whatever it actually emits, usually a group name or a path. App-admin rights
come from auth.app_admin_group_ids when single sign-on is configured in the
chart, and from the App admin groups field on Admin → Single
sign-on when it is set up in the UI.
A service account also has a role tier, editor or admin, which caps what it can call. An
apply account can write any pipeline in its org whatever team owns it, so issue
it as an org-level credential.
From a local account. An app admin creates the account at Admin → Users and assigns its role per organisation there. See Users and teams.
An account with no organisation sees nothing. It can sign in, and that is all. Assigning at least one org role is part of creating a usable account, not a separate administrative step.