mirror of
https://github.com/grafana/grafana.git
synced 2025-02-11 16:15:42 -06:00
19f03e593c
* Docs: update users api * Apply suggestions from code review Co-Authored-By: Marcus Efraimsson <marcus.efraimsson@gmail.com>
608 lines
12 KiB
Markdown
608 lines
12 KiB
Markdown
+++
|
|
title = "User HTTP API "
|
|
description = "Grafana User HTTP API"
|
|
keywords = ["grafana", "http", "documentation", "api", "user"]
|
|
aliases = ["/docs/grafana/latest/http_api/user/"]
|
|
type = "docs"
|
|
[menu.docs]
|
|
name = "Users"
|
|
parent = "http_api"
|
|
+++
|
|
|
|
# User HTTP resources / actions
|
|
|
|
## Search Users
|
|
|
|
`GET /api/users?perpage=10&page=1`
|
|
|
|
**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`
|
|
|
|
**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`
|
|
|
|
**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`
|
|
|
|
**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`
|
|
|
|
**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`
|
|
|
|
**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`
|
|
|
|
**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: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Change Password
|
|
|
|
`PUT /api/user/password`
|
|
|
|
Changes the password for the user
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
PUT /api/user/password HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
|
|
```
|
|
|
|
**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.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/user/orgs HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**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
|
|
|
|
```
|