IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity
ef26c39cbd
grafana/docs/sources/developers/http_api/team.md
Christopher Moyer 8c84d62e3d
Docs: combines all SAML topics into one topic (#49443) 
* combines all SAML topics

* resolves merge conflicts

* makes prettier
2022-05-27 07:42:51 -05:00

479 lines
9.3 KiB
Markdown
Raw Blame History

---
aliases:
- /docs/grafana/latest/developers/http_api/team/
- /docs/grafana/latest/http_api/team/
description: Grafana Team HTTP API
keywords:
- grafana
- http
- documentation
- api
- team
- teams
- group
title: 'Team HTTP API '
---
# 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 you enable `editors_can_admin` configuration flag, then Organization Editors can create teams and manage teams where they are Admin.
- If you enable `editors_can_admin` configuration flag, Editors can find out whether a team that they are not members of exists by trying to create a team with the same name.
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/access-control/custom-role-actions-scopes/" >}}) for more information.
## Team Search With Paging
`GET /api/teams/search?perpage=50&page=1&query=myteam`
or
`GET /api/teams/search?name=myteam`
**Required permissions**
See note in the [introduction]({{< ref "#team-api" >}}) for an explanation.
| Action | Scope |
| ---------- | -------- |
| teams:read | teams:\* |
**Example Request**:
```http
GET /api/teams/search?perpage=10&page=1&query=mytestteam HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
### 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.
#### 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`
**Required permissions**
See note in the [introduction]({{< ref "#team-api" >}}) for an explanation.
| Action | Scope |
| ---------- | -------- |
| teams:read | teams:\* |
**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`
**Required permissions**
See note in the [introduction]({{< ref "#team-api" >}}) for an explanation.
| Action | Scope |
| ------------ | ----- |
| teams:create | N/A |
**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`
**Required permissions**
See note in the [introduction]({{< ref "#team-api" >}}) for an explanation.
| Action | Scope |
| ----------- | -------- |
| teams:write | teams:\* |
**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`
**Required permissions**
See note in the [introduction]({{< ref "#team-api" >}}) for an explanation.
| Action | Scope |
| ------------ | -------- |
| teams:delete | teams:\* |
**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`
**Required permissions**
See note in the [introduction]({{< ref "#team-api" >}}) for an explanation.
| Action | Scope |
| ---------------------- | -------- |
| teams.permissions:read | teams:\* |
**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`
**Required permissions**
See note in the [introduction]({{< ref "#team-api" >}}) for an explanation.
| Action | Scope |
| ----------------------- | -------- |
| teams.permissions:write | teams:\* |
**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`
**Required permissions**
See note in the [introduction]({{< ref "#team-api" >}}) for an explanation.
| Action | Scope |
| ----------------------- | -------- |
| teams.permissions:write | teams:\* |
**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`
**Required permissions**
See note in the [introduction]({{< ref "#team-api" >}}) for an explanation.
| Action | Scope |
| ---------- | -------- |
| teams:read | teams:\* |
**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`
**Required permissions**
See note in the [introduction]({{< ref "#team-api" >}}) for an explanation.
| Action | Scope |
| ----------- | -------- |
| teams:write | teams:\* |
**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
```
Reference in New Issue View Git Blame Copy Permalink