mirror of
https://github.com/grafana/grafana.git
synced 2025-09-24 12:44:17 +08:00
605d056136
* * Teams: Appropriately apply user id filter in /api/teams/:id and /api/teams/search * Teams: Ensure that users searching for teams are only able see teams they have access to * Teams: Require teamGuardian admin privileges to list team members * Teams: Prevent org viewers from administering teams * Teams: Add org_id condition to team count query * Teams: clarify permission requirements in teams api docs * Teams: expand scenarios for team search tests * Teams: mock teamGuardian in tests Co-authored-by: Dan Cech <dcech@grafana.com> * remove duplicate WHERE statement * Fix for CVE-2022-21702 (cherry picked from commit 202d7c190082c094bc1dc13f7fe9464746c37f9e) * Lint and test fixes (cherry picked from commit 3e6b67d5504abf4a1d7b8d621f04d062c048e981) * check content type properly (cherry picked from commit 70b4458892bf2f776302720c10d24c9ff34edd98) * basic csrf origin check (cherry picked from commit 3adaa5ff39832364f6390881fb5b42ad47df92e1) * compare origin to host (cherry picked from commit 5443892699e8ed42836bb2b9a44744ff3e970f42) * simplify url parsing (cherry picked from commit b2ffbc9513fed75468628370a48b929d30af2b1d) * check csrf for GET requests, only compare origin (cherry picked from commit 8b81dc12d8f8a1f07852809c5b4d44f0f0b1d709) * parse content type properly (cherry picked from commit 16f76f4902e6f2188bea9606c68b551af186bdc0) * mentioned get in the comment (cherry picked from commit a7e61811ef8ae558ce721e2e3fed04ce7a5a5345) * add content-type: application/json to test HTTP requests * fix pluginproxy test * Fix linter when comparing errors Co-authored-by: Kevin Minehart <kmineh0151@gmail.com> Co-authored-by: Dan Cech <dcech@grafana.com> Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com> Co-authored-by: Serge Zaitsev <serge.zaitsev@grafana.com> Co-authored-by: Vardan Torosyan <vardants@gmail.com>
385 lines
7.0 KiB
Markdown
385 lines
7.0 KiB
Markdown
+++
|
|
title = "Team HTTP API "
|
|
description = "Grafana Team HTTP API"
|
|
keywords = ["grafana", "http", "documentation", "api", "team", "teams", "group"]
|
|
aliases = ["/docs/grafana/latest/http_api/team/"]
|
|
+++
|
|
|
|
# Team API
|
|
|
|
This API can be used to manage Teams and Team Memberships.
|
|
|
|
Access to these API endpoints is restricted as follows:
|
|
|
|
- All authenticated users are able to view details of teams they are a member of.
|
|
- Organization Admins are able to manage all teams and team members.
|
|
- If the `editors_can_admin` configuration flag is enabled, Organization Editors are able to view details of all teams and to manage teams that they are Admin members of.
|
|
|
|
## Team Search With Paging
|
|
|
|
`GET /api/teams/search?perpage=50&page=1&query=myteam`
|
|
|
|
or
|
|
|
|
`GET /api/teams/search?name=myteam`
|
|
|
|
```http
|
|
GET /api/teams/search?perpage=10&page=1&query=myteam HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
### Using the query parameter
|
|
|
|
Default value for the `perpage` parameter is `1000` and for the `page` parameter is `1`.
|
|
|
|
The `totalCount` field in the response can be used for pagination of the teams list E.g. if `totalCount` is equal to 100 teams and the `perpage` parameter is set to 10 then there are 10 pages of teams.
|
|
|
|
The `query` parameter is optional and it will return results where the query value is contained in the `name` field. Query values with spaces need to be URL encoded e.g. `query=my%20team`.
|
|
|
|
### Using the name parameter
|
|
|
|
The `name` parameter returns a single team if the parameter matches the `name` field.
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
Status Codes:
|
|
|
|
- **200** - Ok
|
|
- **401** - Unauthorized
|
|
- **403** - Permission denied
|
|
- **404** - Team not found (if searching by name)
|
|
|
|
## Get Team By Id
|
|
|
|
`GET /api/teams/:id`
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/teams/1 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
Status Codes:
|
|
|
|
- **200** - Ok
|
|
- **401** - Unauthorized
|
|
- **403** - Permission denied
|
|
- **404** - Team not found
|
|
|
|
## Add Team
|
|
|
|
The Team `name` needs to be unique. `name` is required and `email`,`orgId` is optional.
|
|
|
|
`POST /api/teams`
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/teams HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
Status Codes:
|
|
|
|
- **200** - Ok
|
|
- **401** - Unauthorized
|
|
- **403** - Permission denied
|
|
- **409** - Team name is taken
|
|
|
|
## Update Team
|
|
|
|
There are two fields that can be updated for a team: `name` and `email`.
|
|
|
|
`PUT /api/teams/:id`
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
PUT /api/teams/2 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
Status Codes:
|
|
|
|
- **200** - Ok
|
|
- **401** - Unauthorized
|
|
- **403** - Permission denied
|
|
- **404** - Team not found
|
|
- **409** - Team name is taken
|
|
|
|
## Delete Team By Id
|
|
|
|
`DELETE /api/teams/:id`
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
DELETE /api/teams/2 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
Status Codes:
|
|
|
|
- **200** - Ok
|
|
- **401** - Unauthorized
|
|
- **403** - Permission denied
|
|
- **404** - Failed to delete Team. ID not found
|
|
|
|
## Get Team Members
|
|
|
|
`GET /api/teams/:teamId/members`
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/teams/1/members HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
Status Codes:
|
|
|
|
- **200** - Ok
|
|
- **401** - Unauthorized
|
|
- **403** - Permission denied
|
|
|
|
## Add Team Member
|
|
|
|
`POST /api/teams/:teamId/members`
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/teams/1/members HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
Status Codes:
|
|
|
|
- **200** - Ok
|
|
- **400** - User is already added to this team
|
|
- **401** - Unauthorized
|
|
- **403** - Permission denied
|
|
- **404** - Team not found
|
|
|
|
## Remove Member From Team
|
|
|
|
`DELETE /api/teams/:teamId/members/:userId`
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
DELETE /api/teams/2/members/3 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
Status Codes:
|
|
|
|
- **200** - Ok
|
|
- **401** - Unauthorized
|
|
- **403** - Permission denied
|
|
- **404** - Team not found/Team member not found
|
|
|
|
## Get Team Preferences
|
|
|
|
`GET /api/teams/:teamId/preferences`
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/teams/2/preferences HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Update Team Preferences
|
|
|
|
`PUT /api/teams/:teamId/preferences`
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
PUT /api/teams/2/preferences HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
|
|
```
|
|
|
|
JSON Body Schema:
|
|
|
|
- **theme** - One of: `light`, `dark`, or an empty string for the default theme
|
|
- **homeDashboardId** - The numerical `:id` of a dashboard, default: `0`
|
|
- **timezone** - One of: `utc`, `browser`, or an empty string for the default
|
|
|
|
Omitting a key will cause the current value to be replaced with the system default value.
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: text/plain; charset=utf-8
|
|
|
|
```
|