[release-12.3.0] Restructure As code and developer resources (#113969)

Co-authored-by: Roberto Jiménez Sánchez <roberto.jimenez@grafana.com> Co-authored-by: Anna Urbiztondo <anna.urbiztondo@grafana.com>
2025-11-16 19:06:56 +00:00
parent 0898ec6045
commit 047da1442e
96 changed files with 8186 additions and 230 deletions
--- a/docs/sources/developer-resources/api-reference/http-api/user.md
+++ b/docs/sources/developer-resources/api-reference/http-api/user.md
@@ -0,0 +1,701 @@
+---
+aliases:
+  - ../../../http_api/user/ # /docs/grafana/next/http_api/user/
+  - ../../../developers/http_api/user/ # /docs/grafana/next/developers/http_api/user/
+canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/user/
+description: Grafana User HTTP API
+keywords:
+  - grafana
+  - http
+  - documentation
+  - api
+  - user
+labels:
+  products:
+    - enterprise
+    - oss
+    - cloud
+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
+
+```
+Content-Type: application/json
+Authorization: Basic YWRtaW46YWRtaW4=
+```
+
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+[
+  {
+    "orgId":1,
+    "name":"Main Org.",
+    "role":"Admin"
+  }
+]
+```
+
+## 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
+
+[
+  {
+    "id": 1,
+    "orgId": 1,
+    "name": "MyTestTeam",
+    "email": "",
+    "avatarUrl": "\/avatar\/3f49c15916554246daa714b9bd0ee398",
+    "memberCount": 1
+  }
+]
+```
+
+## 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
+
+{"message":"Dashboard starred!"}
+```
+
+## 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
+
+{"message":"Dashboard unstarred"}
+```
+
+## 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
+
+[
+  {
+    "id": 361,
+    "isActive": true,
+    "clientIp": "127.0.0.1",
+    "browser": "Chrome",
+    "browserVersion": "72.0",
+    "os": "Linux",
+    "osVersion": "",
+    "device": "Other",
+    "createdAt": "2019-03-05T21:22:54+01:00",
+    "seenAt": "2019-03-06T19:41:06+01:00"
+  },
+  {
+    "id": 364,
+    "isActive": false,
+    "clientIp": "127.0.0.1",
+    "browser": "Mobile Safari",
+    "browserVersion": "11.0",
+    "os": "iOS",
+    "osVersion": "11.0",
+    "device": "iPhone",
+    "createdAt": "2019-03-06T19:41:19+01:00",
+    "seenAt": "2019-03-06T19:41:21+01:00"
+  }
+]
+```
+
+## 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
+
+{
+  "authTokenId": 364
+}
+```
+
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+{
+  "message": "User auth token revoked"
+}
+```