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 | |
| 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 |
| 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.