Project: Grafana (Observability and Analysis / Observability)
File: user.md

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 The Users HTTP API does not currently work with an API Token. API Tokens are linked to an organization and an organization role. They cannot be given the permission of server users access, only users can be given that permission. To use these API calls you can use Basic Auth and the Grafana user must have the Grafana Admin role. API Tokens can be used with Organization HTTP API to get users of specific organization. If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to for more information. `GET /api/users?perpage=10&page=1&sort=login-asc,email-asc` Required permissions See note in the 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 [ { "id": 1, "name": "Admin", "login": "admin", "email": "admin@mygraf.com", "isAdmin": true, "isDisabled": false, "lastSeenAt": "2020-04-10T20:29:27+03:00", "lastSeenAtAge": "2m", "authLabels": ["OAuth"] }, { "id": 2, "name": "User", "login": "user", "email": "user@mygraf.com", "isAdmin": false, "isDisabled": false, "lastSeenAt": "2020-01-24T12:38:47+02:00", "lastSeenAtAge": "2M", "authLabels": [] } ] ``` `GET /api/users/search?perpage=10&page=1&query=mygraf&sort=login-asc,email-asc` Required permissions See note in the 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

200 Content-Type: application/json { "totalCount": 2, "users": [ { "id": 1, "name": "Admin", "login": "admin", "email": "admin@mygraf.com", "isAdmin": true, "isDisabled": false, "lastSeenAt": "2020-04-10T20:29:27+03:00", "lastSeenAtAge': "2m", "authLabels": ["OAuth"] }, { "id": 2, "name": "User", "login": "user", "email": "user@mygraf.com", "isAdmin": false, "isDisabled": false, "lastSeenAt": "2020-01-24T12:38:47+02:00", "lastSeenAtAge": "2M", "authLabels": [] } ], "page": 1, "perPage": 10 } ``` `GET /api/users/:id` Required permissions See note in the 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 { "id": "1", "email": "user@mygraf.com", "name": "admin", "login": "admin", "theme": "light", "orgId": 1, "isGrafanaAdmin": true, "isDisabled": true, "isExternal": false, "authLabels": [], "updatedAt": "2019-09-09T11:31:26+01:00", "createdAt": "2019-09-09T11:31:26+01:00", "avatarUrl": "" } ``` `GET /api/users/lookup?loginOrEmail=user@mygraf.com` Required permissions See note in the 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 { "id": 1, "email": "user@mygraf.com", "name": "admin", "login": "admin", "theme": "light", "orgId": 1, "isGrafanaAdmin": true, "isDisabled": false, "isExternal": false, "authLabels": null, "updatedAt": "2019-09-25T14:44:37+01:00", "createdAt": "2019-09-25T14:44:37+01:00", "avatarUrl":"" } ``` `PUT /api/users/:id` Required permissions See note in the 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= { "email":"user@mygraf.com", "name":"User2", "login":"user", "theme":"light" } ``` Requires basic authentication and that the authenticated user is a Grafana Admin. Example Response: ```http HTTP/1.1 200 Content-Type: application/json {"message":"User updated"} ``` `GET /api/users/:id/orgs` Required permissions See note in the 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 [ { "orgId":1, "name":"Main Org.", "role":"Admin" } ] ``` `GET /api/users/:id/teams` Required permissions See note in the 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 [ { "id":1, "orgId":1, "name":"team1", "email":"", "avatarUrl":"/avatar/3fcfe295eae3bcb67a49349377428a66", "memberCount":1 } ] ``` `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 { "id":1,

"name":"Admin", "login":"admin", "theme":"light", "orgId":1, "isGrafanaAdmin":true, "isDisabled":false "isExternal": false, "authLabels": [], "updatedAt": "2019-09-09T11:31:26+01:00", "createdAt": "2019-09-09T11:31:26+01:00", "avatarUrl": "" } ``` `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= { "oldPassword": "old_password", "newPassword": "new_password" } ``` Example Response: ```http HTTP/1.1 200 Content-Type: application/json {"message":"User password changed"} ``` 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@<yourgrafanahost>:3000/api/user/password ``` `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 {"message":"Active organization changed"} ``` `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 {"message":"Active organization changed"} ``` `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 [ { "orgId":1, "name":"Main Org.", "role":"Admin" } ] ``` `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 } ] ``` `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 {"message":"Dashboard starred!"} ``` `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 {"message":"Dashboard unstarred"} ``` `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" } ] ``` `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" } ``` {{% docs/reference %}} {{% /docs/reference %}}