mirror of
https://github.com/grafana/grafana.git
synced 2025-07-28 13:32:24 +08:00
c1c48dd610
* Use relative aliases for all non-current Grafana aliases
Prevents non-latest documentation "stealing" the page away from latest
and through permanent redirects for latest pages that no longer exist.
The redirected pages are indexed by search engines but our robots.txt
forbids them crawling the non-latest page.
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Remove aliases from shared pages
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Rewrite all current latest aliases to be next
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Fix typo in latest alias
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Remove all current page aliases
find docs/sources -type f -name '*.md' -exec sed -z -i 's#\n *- /docs/grafana/next/[^\n]*\n#\n#' {} \;
find docs/sources -type f -name '*.md' -exec sed -Ez -i 's#\n((aliases:\n *-)|aliases:\n)#\n\2#' {} \;
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Prettier
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
671 lines
13 KiB
Markdown
671 lines
13 KiB
Markdown
---
|
|
aliases:
|
|
- ../../http_api/user/
|
|
description: Grafana User HTTP API
|
|
keywords:
|
|
- grafana
|
|
- http
|
|
- documentation
|
|
- api
|
|
- user
|
|
title: User HTTP API
|
|
---
|
|
|
|
# User API
|
|
|
|
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../administration/roles-and-permissions/access-control/custom-role-actions-scopes/" >}}) for more information.
|
|
|
|
## Search Users
|
|
|
|
`GET /api/users?perpage=10&page=1`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ---------- | --------------- |
|
|
| users:read | global.users:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/users HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
Default value for the `perpage` parameter is `1000` and for the `page` parameter is `1`. Requires basic authentication and that the authenticated user is a Grafana Admin.
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Search Users with Paging
|
|
|
|
`GET /api/users/search?perpage=10&page=1&query=mygraf`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ---------- | --------------- |
|
|
| users:read | global.users:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/users/search?perpage=10&page=1&query=mygraf HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
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 user list E.g. if `totalCount` is equal to 100 users and the `perpage` parameter is set to 10 then there are 10 pages of users. The `query` parameter is optional and it will return results where the query value is contained in one of the `name`, `login` or `email` fields. Query values with spaces need to be URL encoded e.g. `query=Jane%20Doe`.
|
|
|
|
Requires basic authentication and that the authenticated user is a Grafana Admin.
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
{
|
|
```
|
|
|
|
## Get single user by Id
|
|
|
|
`GET /api/users/:id`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ---------- | --------------- |
|
|
| users:read | global.users:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/users/1 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
Requires basic authentication and that the authenticated user is a Grafana Admin.
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Get single user by Username(login) or Email
|
|
|
|
`GET /api/users/lookup?loginOrEmail=user@mygraf.com`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ---------- | --------------- |
|
|
| users:read | global.users:\* |
|
|
|
|
**Example Request using the email as option**:
|
|
|
|
```http
|
|
GET /api/users/lookup?loginOrEmail=user@mygraf.com HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Request using the username as option**:
|
|
|
|
```http
|
|
GET /api/users/lookup?loginOrEmail=admin HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
Requires basic authentication and that the authenticated user is a Grafana Admin.
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## User Update
|
|
|
|
`PUT /api/users/:id`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ----------- | --------------- |
|
|
| users:write | global.users:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
PUT /api/users/2 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
|
|
```
|
|
|
|
Requires basic authentication and that the authenticated user is a Grafana Admin.
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Get Organizations for user
|
|
|
|
`GET /api/users/:id/orgs`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ---------- | --------------- |
|
|
| users:read | global.users:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/users/1/orgs HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
Requires basic authentication and that the authenticated user is a Grafana Admin.
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Get Teams for user
|
|
|
|
`GET /api/users/:id/teams`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ---------- | --------------- |
|
|
| users:read | global.users:\* |
|
|
| teams:read | teams:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/users/1/teams HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
Requires basic authentication and that the authenticated user is a Grafana Admin.
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## User
|
|
|
|
## Actual User
|
|
|
|
`GET /api/user`
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/user HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
Requires basic authentication.
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Change Password
|
|
|
|
`PUT /api/user/password`
|
|
|
|
Changes the password for the user. Requires basic authentication.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
PUT /api/user/password HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
**Change Password with a Script**
|
|
|
|
If you need to change a password with a script, here is an example of changing the Admin password using curl with basic auth:
|
|
|
|
```bash
|
|
curl -X PUT -H "Content-Type: application/json" -d '{
|
|
"oldPassword": "oldpass",
|
|
"newPassword": "newpass",
|
|
"confirmNew": "newpass"
|
|
}' http://admin:oldpass@<your_grafana_host>:3000/api/user/password
|
|
```
|
|
|
|
## Switch user context for a specified user
|
|
|
|
`POST /api/users/:userId/using/:organizationId`
|
|
|
|
Switch user context to the given organization. Requires basic authentication and that the authenticated user is a Grafana Admin.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/users/7/using/2 HTTP/1.1
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Switch user context for signed in user
|
|
|
|
`POST /api/user/using/:organizationId`
|
|
|
|
Switch user context to the given organization.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/user/using/2 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Organizations of the actual User
|
|
|
|
`GET /api/user/orgs`
|
|
|
|
Return a list of all organizations of the current user. Requires basic authentication.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/user/orgs HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Teams that the actual User is member of
|
|
|
|
`GET /api/user/teams`
|
|
|
|
Return a list of all teams that the current user is member of.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/user/teams HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Star a dashboard
|
|
|
|
`POST /api/user/stars/dashboard/:dashboardId`
|
|
|
|
Stars the given Dashboard for the actual user.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/user/stars/dashboard/1 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Unstar a dashboard
|
|
|
|
`DELETE /api/user/stars/dashboard/:dashboardId`
|
|
|
|
Deletes the starring of the given Dashboard for the actual user.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
DELETE /api/user/stars/dashboard/1 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Auth tokens of the actual User
|
|
|
|
`GET /api/user/auth-tokens`
|
|
|
|
Return a list of all auth tokens (devices) that the actual user currently have logged in from.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/user/auth-tokens HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Revoke an auth token of the actual User
|
|
|
|
`POST /api/user/revoke-auth-token`
|
|
|
|
Revokes the given auth token (device) for the actual user. User of issued auth token (device) will no longer be logged in
|
|
and will be required to authenticate again upon next activity.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/user/revoke-auth-token HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|