Organisations and Teams

A new joiner cannot see the SRE dashboard. They have a Grafana account and have been added to the SRE team. Why is the dashboard still empty for them? Because the team is not the same as a folder permission. The team is a group of users; the folder permission grants the team access to the folder. Either the SRE folder’s permissions reference the team correctly, or the dashboard is invisible to them.

This lesson is the four-quadrant model: organisation (the tenant), folder (the grouping of dashboards), team (the grouping of users), role (the kind of access). Knowing which one solves a request is half the work; the other half is knowing how to express it.

What organisations, teams, folders, and roles are

In Grafana 11, there are four orthogonal concepts:

• Organisation — a tenant. Holds users, data sources, dashboards, alert rules, and folders. A Grafana server hosts one or many; the typical production setup is one org (id 1) on a Grafana instance owned by one business unit. Cloud Grafana uses one org per stack.
• Folder — a named container of dashboards and other folders. Folders are the namespace that permissions attach to. Permissions may be set at the folder root and inherited by all contained dashboards (managed permissions) or set on each dashboard (legacy permissions).
• Team — a named group of users inside an organisation. Teams are how Grafana expresses “give everyone on SRE the same level of access”. A user can be a member of any number of teams. A team does not own dashboards by itself; the team must be granted a folder permission.
• Role — a property of the user (or the binding user + org
  • team). The four basic roles are Viewer, Editor, Admin, and Grafana Admin. The basic role sets the floor of what a user can do; folder permissions can raise the ceiling on specific folders.

+--- Organisation (tenant) -----------------------------------+
|                                                              |
|   +--- Folder "SRE" --------------------------------------+  |
|   |  permission: team_sre -> Edit                       |  |
|   |                                                       |  |
|   |  +--- Dashboard "prod-overview"                      |  |
|   |  +--- Dashboard "on-call-shift"                      |  |
|   |  +--- Folder "incidents-2026" (nested)               |  |
|   |                                                       |  |
|   +-------------------------------------------------------+  |
|                                                              |
|   +--- Folder "engineering" -----------------------------+   |
|   |  permission: team_eng -> View                       |  |
|   |  permission: team_sre -> Edit                      |   |
|   +------------------------------------------------------+   |
|                                                              |
|   Team "team_sre"  members: alice, bob, carol                |
|   Team "team_eng"  members: dev1, dev2, dev3                 |
|                                                              |
|   alice:  basic role Viewer                                   |
|           team_sre grants Edit on folder "SRE"                |
|           effective role on folder "SRE": Editor              |
|           effective role on folder "engineering": Viewer      |
+--------------------------------------------------------------+

The “bridged” model in the diagram is the relevant detail. A team permission on a folder overrides the basic role on that folder only. This is what makes SRE engineers able to edit the SRE folder while remaining Viewers on everything else.

Why a sysadmin cares

Three recurring ticket types land here.

1. “I cannot see the dashboard I was told exists.” Most often a folder-permission grant missing for the user’s team, or a nested folder whose root permission was not inherited.
2. “I cannot edit the dashboard I just made.” The user has Viewer basic role and the folder is View-only. Either give them Editor role (a basic-role grant) or grant their team Editor on the folder.
3. “The off-boarder’s account still works.” A user was deleted from the IdP but a stale Grafana team membership remains. Team sync is the fix and the lesson below.

Each of these tickets has a one-API-call diagnosis once you know where to look.

How it works

The permissions model has three layers, evaluated in order, the first match wins.

  request to view / edit / admin a dashboard
                  |
                  v
+----------------------------------------------------------+
|  1. Managed folder permissions (per folder, per team)    |
|     - if a team permission matches, return Allow / Deny  |
+----------------------------------------------------------+
                  | no match
                  v
+----------------------------------------------------------+
|  2. Per-dashboard ACL (legacy permissions model)          |
|     - if set, return that Allow / Deny                   |
+----------------------------------------------------------+
                  | no match
                  v
+----------------------------------------------------------+
|  3. Basic role of the user in the organisation           |
|     - Viewer = read most things; Editor = also write;     |
|       Admin = also manage; Grafana Admin = also global   |
+----------------------------------------------------------+

The “managed” folder permissions are the recommended model. They live on the folder, are inherited by descendants, and are updated in one place when a team membership changes. The per-dashboard ACL model predates folders and remains for backwards compatibility; new dashboards should always live in a folder with managed permissions.

How to configure it

File-based provisioning is the only sustainable configuration for folders and teams. Below are three short provisioning files that establish a complete starting layout.

# /etc/grafana/provisioning/teams/teams.yaml
apiVersion: 1
teams:
  - name:        sre
    orgId:       1
    email:       sre@example.com
    description: Site Reliability Engineering
    # Team members should be supplied by the identity provider
    # via team_sync. Listing them here is for static fallback.
    members:
      - userLogin: alice@example.com
        permission: Admin   # team permission for the team's own page
      - userLogin: bob@example.com
        permission: Member

# /etc/grafana/provisioning/folders/folders.yaml
apiVersion: 1
folders:
  - title:       SRE
    orgId:       1
    uid:         sre
    description: Operational dashboards owned by SRE
  - title:       Engineering
    orgId:       1
    uid:         engineering
  - title:       Finance
    orgId:       1
    uid:         finance

# /etc/grafana/provisioning/access-control/permissions.yaml
# File-based managed folder permissions are the recommended
# model. Each entry ties a team to a folder + role.
apiVersion: 1
permissions:
  - folderUid: sre
    team:      sre
    permission: Edit
  - folderUid: engineering
    team:      sre
    permission: View
  - folderUid: engineering
    team:      engineering
    permission: Edit

And the matching grafana.ini snippet for team sync through a generic OIDC provider:

[auth.generic_oauth]
enabled          = true
name             = SSO
client_id        = ${OIDC_CLIENT_ID}
client_secret    = ${OIDC_CLIENT_SECRET}
scopes           = openid profile email groups
auth_url         = https://idp.example.com/authorize
token_url        = https://idp.example.com/token
api_url          = https://idp.example.com/userinfo
role_attribute_path = contains(groups, 'sre') && 'Admin' || 'Viewer'

[auth.generic_oauth.team_sync]
enabled   = true
team_id_attribute = groups    # claim in the OIDC userinfo
auto_assign_org_id = 1
# Map an IdP group claim to a Grafana team.
group_synchronization_enabled = true
groups_to_teams:
  - group_id: /sre/
    team_id:  sre
    team_role: Member
  - group_id: /eng/
    team_id:  engineering
    team_role: Member
  - group_id: /sre-leads/
    team_id:  sre
    team_role: Admin

How to validate it

Three API calls confirm the right answer for a typical ticket. Each is READ-ONLY.

# 1. Confirm the folder exists and read its permissions.
curl -sf -u "grafana-admin:$GF_ADMIN_PASSWORD" \
  http://grafana:3000/api/folders/uid/sre/permissions | jq

[
  { "id": 1, "folderUid": "sre", "teamId": 1, "team": "sre",
    "userId": 0, "role": null, "permission": 2, "permissionName": "Edit" }
]

# 2. Confirm the team has the right members.
curl -sf -u "grafana-admin:$GF_ADMIN_PASSWORD" \
  http://grafana:3000/api/teams/1/members | jq '.[] | {login, permission}'

{ "login": "alice@example.com", "permission": 4 }
{ "login": "bob@example.com",   "permission": 2 }

# 3. Confirm what a specific user can see. The simulated user
#    credential here is an admin's debug token; in production,
#    replace with a service-account token scoped to the user.
curl -sf -u "alice-token:$GF_ALICE_TOKEN" \
  http://grafana:3000/api/access-control/user/permissions \
  | jq '.permissions[] | select(.scope | test("folder:sre"))'

{ "action": "folders:read",   "scope": "folders:uid:sre" }
{ "action": "folders:write",  "scope": "folders:uid:sre" }
{ "action": "dashboards:read","scope": "folders:uid:sre" }

The right answer for “alice can see the SRE folder” is the presence of the read and write actions on folders:uid:sre in this list. Absence of an entry means the access is denied.

How it can fail

Five high-frequency failure shapes.

1. Team present in the API but no folder permissions. The team exists and has members, but no row in the folder’s permissions reference it. Users on the team see no dashboards in the folder because the inheritance is empty.
2. Nested folder permissions not inherited. A team has Edit on the parent folder but no entry on the child. In managed-mode this should be inherited; if the child was switched to per-dashboard permissions, the inheritance breaks.
3. Per-dashboard ACL set, overriding the folder. A dashboard has its own ACL, the team’s permission on the folder is ignored. This is the legacy model and a constant source of confusion.
4. Basic role lower than folder role. A user has basic role Viewer and folder Edit permission on the team. The user cannot edit the dashboard because the basic role is the floor. Folder grants raise the ceiling, but not above the floor.
5. IdP team sync disabled. A user is added to the IdP group but their Grafana team membership is not updated. The OIDC team_sync block is missing or the groups_to_teams list is empty.
6. Off-boarder still showing in active teams. The user was removed from the IdP group but a Grafana-side membership remains. Team sync only adds and updates members; some IdP integrations require a remove_on_logout flag set.

How to troubleshoot it

The diagnosis order for the “user cannot see the dashboard” ticket:

1. List the user’s teams. /api/teams/search?query=<user>. Empty list means the user has no team and inherits only the basic role.
2. List the folder’s permissions. /api/folders/uid/<uid>/permissions. The team must be in this list with the role expected.
3. List the dashboard’s ACL if any. /api/dashboards/uid/<uid>/acl. A non-empty result means legacy per-dashboard permissions exist and may be overriding the folder.
4. Read the user’s effective permissions. /api/access-control/user/permissions filtered to the folder UID. The presence (or absence) of an action explains the symptom.
5. Check the basic role. /api/org/users/<user>. A Editor basic role plus a folder-granted Edit is fine; a Viewer basic role plus a folder-granted Edit is unusual and worth confirming.
6. Check the IdP group claim. Make the user log out and back in; the OIDC team_sync runs on each login in the typical config. If the membership appears only after a manual team-edit, the IdP mapping is broken.

Security implications

• Permissions default to permissive. A folder without a specific grant falls through to the user’s basic role. New folders created via the UI default to allowing Edit for the creator only; provisioned folders inherit the org default and may inherit existing permissions. Audit new folders.
• Grafana Admin is global. Members of this role can bypass folder permissions. Restrict the basic role Grafana Admin to one or two named accounts; never grant it through a team sync mapping.
• Role-attribute mapping is arbitrary. An OIDC mapping contains(groups, 'sre') && 'Admin' is a one-line privilege-escalation source. Require two-person review for the [auth.*.role_attribute_path] setting.
• IdP-issued tokens must expire. Set IdP-side token lifetimes under one hour; a long-lived token captured at the desk of a Grafana admin is a Grafana admin breach.
• Per-dashboard ACL is the dangerous legacy model. Auditing for ACLs in a large Grafana is hard. Move all production dashboards under folders with managed permissions.

Performance implications

• Permission evaluation is per-request. A dashboard load evaluates the permission tree once for the user; the cost is in the few-millisecond range and is amortised over the rest of the request. Permission checks are not a bottleneck in normal operation.
• A very large number of teams (over a few hundred) makes the permission API responses slow. This is rare in practice; it surfaces as slow dashboard loads.
• Team sync polls the IdP at each login. A high-frequency login (an aggressive health check) slows IdP rate limits. Do not chain Grafana into an inbound loop.

Production guidance

• Use one organisation per business unit. Resist the urge to use one org per environment; route dev / staging / prod through folders and data sources, not orgs.
• Adopt managed folder permissions for every dashboard. The per-dashboard ACL is for backwards compatibility, not for new work.
• Use IdP team sync; do not maintain Grafana team membership by hand. The off-boarding story needs to be auditable from one place.
• Treat Grafana Admin as break-glass access. Confine it to on-call managers; never grant it via team sync.
• Review the contents of /api/access-control/user/permissions for a fresh user during onboarding; the output is the source of truth for what they can see.

Verification

You should now be able to answer:

• What does an organisation own that a folder does not?
• Why does a team membership alone not give a user access to a folder?
• Where does a managed folder permission live and what does it inherit?
• What is the difference between the basic role on the user and a folder-granted role on the team?
• How does Grafana learn a new joiner belongs to a team without manual intervention?

Quiz