Skip to main content

Managing Teams

1. Creating Teams

Example: Create Team via API

const team = {
  name: "Backend Engineers",
  email: "backend@example.com",
  orgId: 1
};

const response = await fetch("/api/teams", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API_TOKEN>"
  },
  body: JSON.stringify(team)
});

const newTeam = await response.json();
Field Description Required Default
name Name of the team Yes
email Team email address (optional) No
orgId Organization ID to create team in Yes
Note: Team names must be unique within an organization.
Warning: Ensure the user has Admin permissions to create teams.

2. Adding Users to Teams

Field Description Example
teamId Unique identifier of the team to add users to 123
userIds Array of user IDs to add to the team [456, 789]
role Role assigned to the user in the team (Viewer, Editor, Admin) Editor

Example: Adding Users to a Team via API

const addUserToTeam = async () => {
  const response = await fetch("/api/teams/123/members", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer <token>"
    },
    body: JSON.stringify({
      userIds: [456, 789],
      role: "Editor"
    })
  });

  const result = await response.json();
  console.log(result);
};
Note: The role field is optional and defaults to Viewer if not specified.
Warning: Ensure that the user has appropriate permissions to manage team memberships.

3. Setting Team Roles

Role Description Permissions Notes
Admin Full access to all features and settings Read, write, delete, manage users, manage dashboards, manage data sources Default role for administrators
Editor Can create and edit dashboards, manage data sources Read, write, delete dashboards, manage data sources Can view and edit most resources but cannot manage users or settings
Viewer Read-only access to dashboards and data Read dashboards, view data sources Best for users who only need to observe and analyze data

Example: Assigning a Team Role via API

curl -X PUT "http://localhost:3000/api/teams/1/members" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 123,
    "role": "Editor"
  }'
Note: Team roles can also be managed through the Grafana UI under Configuration > Teams.

4. Configuring Team Permissions

Permission Level Description
Admin Global Full access to all Grafana features and settings, including user management and data source configuration.
Editor Global Can create, edit, and delete dashboards, folders, and data sources. Cannot manage users or settings.
Viewer Global Read-only access to dashboards and data sources. Cannot make changes or create new content.
Org Admin Organization Full access within the organization, including managing teams and users.
Team Admin Team Manage team members and permissions within the team scope.

Example: Setting Team Permissions via API

curl -X PUT "http://localhost:3000/api/teams/1/permissions" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "permission": "Editor"
  }'
Note: Team permissions can be managed via the Grafana UI or API. Permissions are inherited from organization-level settings unless overridden at the team level.

5. Using Team Sync

Team Sync in Grafana allows you to synchronize team memberships with external identity providers such as LDAP or Active Directory.

Setting Description Default
ldap.sync_ttl Time in seconds to cache the LDAP group membership 300
ldap.allow_sign_up Allow users to sign up automatically if they don't exist true
ldap.group_sync Enable or disable group synchronization false

Example: Configure LDAP Team Sync

[auth.ldap]
; Enable LDAP group synchronization
group_sync = true

; Set cache TTL for group membership (in seconds)
sync_ttl = 600

; Allow new users to sign up
allow_sign_up = true
Note: Team Sync requires appropriate permissions in your LDAP or Active Directory configuration to read group memberships.
Warning: Ensure that the LDAP server is accessible and that the configured user has read access to group information.

6. Setting Team Preferences

Preference Description Default Value Notes
team.email Email address for team notifications Not set Required for email alerts
team.timezone Timezone for team dashboards and alerts Browser timezone Overrides user settings
team.locale Language locale for team UI en-US Supports multiple locales
team.theme UI theme preference (dark/light) light Can be overridden per user

Example: Setting Team Preferences via API

const teamPreferences = {
  "team.email": "alerts@company.com",
  "team.timezone": "America/New_York",
  "team.locale": "en-US",
  "team.theme": "dark"
};

fetch("/api/teams/1/preferences", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
  },
  body: JSON.stringify(teamPreferences)
});
Note: Team preferences can be overridden by individual user preferences in the Grafana UI.
Warning: Setting team.email is required to enable email-based alert notifications.

7. Managing Team Dashboards

Property Description Default Value Notes
dashboard.title Title of the dashboard "" Required field
dashboard.uid Unique identifier for the dashboard null Auto-generated if not provided
dashboard.folderId Folder ID where the dashboard is stored 0 0 means root folder
dashboard.timeFrom Default start time for dashboard queries "now-1h" Can use relative or absolute times
dashboard.timeTo Default end time for dashboard queries "now" Can use relative or absolute times

Example: Creating a Team Dashboard

{
  "dashboard": {
    "title": "Team Metrics Dashboard",
    "uid": "team-metrics-dash",
    "folderId": 123,
    "timeFrom": "now-6h",
    "timeTo": "now"
  },
  "overwrite": true
}
Note: Team dashboards can be shared across multiple teams by assigning them to a specific folder or using team-level permissions.

Key Features of Team Dashboards

  • Shared access control for team members
  • Centralized storage in folders
  • Time range configuration for data visualization
  • UID-based identification for easy referencing

8. Using Team Variables

Variable Type Description Usage
team.name String Name of the team {{team.name}}
team.id Number Unique identifier for the team {{team.id}}
team.members Array List of team member IDs {{team.members}}
team.permissions Object Permissions assigned to the team {{team.permissions}}

Example: Team Variable in Dashboard

{
  "panels": [
    {
      "title": "Team Dashboard",
      "targets": [
        {
          "expr": "up{team_id="{{team.id}}"}",
          "legendFormat": "{{team.name}} - {{__name__}}"
        }
      ]
    }
  ]
}
Note: Team variables can be used in queries, annotations, and template variables to dynamically filter data based on team context.

9. Deleting Teams

Property Value Description
teamId string The unique identifier of the team to delete
forceDelete boolean If true, deletes the team and all associated resources; if false, prevents deletion if members exist

Example: Delete a Team

const teamId = 'team-123';
const forceDelete = true;

// Delete the team and all associated resources
await grafanaClient.deleteTeam(teamId, forceDelete);
Note: Deleting a team is irreversible and removes all associated permissions and resources.
Warning: If forceDelete is false and the team has members, deletion will be blocked.

10. Using Team API

Property Description Example
teamId Unique identifier for the team 123
name Name of the team Backend Developers
email Team email address backend-devs@example.com
orgId Organization ID the team belongs to 1

Example: Create a new team

{
  "name": "Backend Developers",
  "email": "backend-devs@example.com",
  "orgId": 1
}

Example: Get team details

curl -H "Authorization: Bearer <API_TOKEN>" \
  http://localhost:3000/api/teams/123

Example: Update team permissions

{
  "name": "Backend Developers",
  "email": "backend-devs@example.com",
  "orgId": 1,
  "permissions": [
    {
      "action": "teams:read",
      "scope": "team:123"
    },
    {
      "action": "teams:write",
      "scope": "team:123"
    }
  ]
}
Note: The Team API requires Admin or Editor permissions to manage teams.

Was this article helpful?