mirror of https://github.com/grafana/grafana.git
700 lines
15 KiB
Markdown
700 lines
15 KiB
Markdown
---
|
|
aliases:
|
|
- ../../http_api/user/
|
|
canonical: /docs/grafana/latest/developers/http_api/user/
|
|
description: Grafana User HTTP API
|
|
keywords:
|
|
- grafana
|
|
- http
|
|
- documentation
|
|
- api
|
|
- user
|
|
labels:
|
|
products:
|
|
- enterprise
|
|
- oss
|
|
title: User HTTP API
|
|
refs:
|
|
role-based-access-control-permissions:
|
|
- pattern: /docs/grafana/
|
|
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/custom-role-actions-scopes/
|
|
- pattern: /docs/grafana-cloud/
|
|
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/custom-role-actions-scopes/
|
|
---
|
|
|
|
# User API
|
|
|
|
{{< admonition type="caution" >}}
|
|
You can't authenticate to the User HTTP API with service account tokens.
|
|
Service accounts are limited to an organization and an organization role.
|
|
They can't be granted [Grafana server administrator permissions](/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/#grafana-server-administrators).
|
|
|
|
Alternatively, you can use the [Organization HTTP API](/docs/grafana/<GRAFANA_VERSION>/developers/http_api/org/#current-organization-api) with service account tokens to manage users in a specific organization
|
|
|
|
To use these API endpoints you have to use Basic authentication and the Grafana user must have the Grafana server administrator permission.
|
|
|
|
The `admin` user that Grafana is provisioned with by default has permissions to use these API endpoints.
|
|
{{< /admonition >}}
|
|
|
|
For Grafana Cloud customers, refer to [Organization HTTP API](/docs/grafana/latest/developers/http_api/org/) for finding users with the org Admin role.
|
|
|
|
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](ref:role-based-access-control-permissions) for more information.
|
|
|
|
## Search Users
|
|
|
|
`GET /api/users?perpage=10&page=1&sort=login-asc,email-asc`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#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.
|
|
|
|
The `sort` param is an optional comma separated list of options to order the search result. Accepted values for the sort filter are: `login-asc`, `login-desc`, `email-asc`, `email-desc`, `name-asc`, `name-desc`, `lastSeenAtAge-asc`, `lastSeenAtAge-desc`. By default, if `sort` is not specified, the user list will be ordered by `login`, `email` in ascending order.
|
|
|
|
**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&sort=login-asc,email-asc`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#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`.
|
|
|
|
The `sort` param is an optional comma separated list of options to order the search result. Accepted values for the sort filter are: `login-asc`, `login-desc`, `email-asc`, `email-desc`, `name-asc`, `name-desc`, `lastSeenAtAge-asc`, `lastSeenAtAge-desc`. By default, if `sort` is not specified, the user list will be ordered by `login`, `email` in ascending order.
|
|
|
|
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](#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](#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: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**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](#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](#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](#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/uid/:uid`
|
|
|
|
Stars the given Dashboard for the actual user.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/user/stars/dashboard/uid/BqokFhx7z 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/uid/:uid`
|
|
|
|
Deletes the starring of the given Dashboard for the actual user.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
DELETE /api/user/stars/dashboard/uid/BqokFhx7z 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
|
|
|
|
```
|