---
title: "User HTTP API | Grafana documentation"
description: "Grafana User HTTP API"
---

# User API

> Note
> 
> Starting in Grafana 13, `/api` endpoints are being deprecated in favor of the `/apis` route. Note that while Grafana is working on migrating existing APIs, currently there may not be an exact match to the legacy API you’re using.
> 
> **This change doesn’t disrupt or break your current setup**. Legacy APIs are not being disabled and remain fully accessible and operative, but `/api` routes will no longer be updated.
> 
> To learn more refer to the [new API structure in Grafana](/docs/grafana/next/developer-resources/api-reference/http-api/apis/).

> 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/next/administration/roles-and-permissions/#grafana-server-administrators).
> 
> Alternatively, you can use the [Organization HTTP API](/docs/grafana/next/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.

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](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-control/custom-role-actions-scopes/) 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.

Expand table

| Action     | Scope          |
|------------|----------------|
| users:read | global.users:* |

**Example Request**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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": []
  }
]
```

## 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.

Expand table

| Action     | Scope          |
|------------|----------------|
| users:read | global.users:* |

**Example Request**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
HTTP/1.1 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 single user by Id

`GET /api/users/:id`

**Required permissions**

See note in the [introduction](#user-api) for an explanation.

Expand table

| Action     | Scope          |
|------------|----------------|
| users:read | global.users:* |

**Example Request**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 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.

Expand table

| Action     | Scope          |
|------------|----------------|
| users:read | global.users:* |

**Example Request using the email as option**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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":""
}
```

## User Update

`PUT /api/users/:id`

**Required permissions**

See note in the [introduction](#user-api) for an explanation.

Expand table

| Action      | Scope          |
|-------------|----------------|
| users:write | global.users:* |

**Example Request**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
HTTP/1.1 200
Content-Type: application/json

{"message":"User updated"}
```

## Get Organizations for user

`GET /api/users/:id/orgs`

**Required permissions**

See note in the [introduction](#user-api) for an explanation.

Expand table

| Action     | Scope          |
|------------|----------------|
| users:read | global.users:* |

**Example Request**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
HTTP/1.1 200
Content-Type: application/json

[
  {
    "orgId":1,
    "name":"Main Org.",
    "role":"Admin"
  }
]
```

## Get Teams for user

`GET /api/users/:id/teams`

**Required permissions**

See note in the [introduction](#user-api) for an explanation.

Expand table

| Action     | Scope          |
|------------|----------------|
| users:read | global.users:* |
| teams:read | teams:*        |

**Example Request**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
HTTP/1.1 200
Content-Type: application/json

[
  {
    "id":1,
    "orgId":1,
    "name":"team1",
    "email":"",
    "avatarUrl":"/avatar/3fcfe295eae3bcb67a49349377428a66",
    "memberCount":1
  }
]
```

## User

## Actual User

`GET /api/user`

**Example Request**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
GET /api/user HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
```

Requires basic authentication.

**Example Response**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "email":"admin@mygraf.com",
  "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": ""
}
```

## Change Password

`PUT /api/user/password`

Changes the password for the user. Requires basic authentication.

**Example Request**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
POST /api/users/7/using/2 HTTP/1.1
Authorization: Basic YWRtaW46YWRtaW4=
```

**Example Response**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
HTTP/1.1 200
Content-Type: application/json

{"message":"Active organization changed"}
```

## Switch user context for signed in user

`POST /api/user/using/:organizationId`

Switch user context to the given organization.

**Example Request**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
POST /api/user/using/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```

**Example Response**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
HTTP/1.1 200
Content-Type: application/json

{"message":"Active organization changed"}
```

## 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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
GET /api/user/orgs HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
```

**Example Response**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
GET /api/user/teams HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```

**Example Response**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
POST /api/user/stars/dashboard/uid/BqokFhx7z HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```

**Example Response**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
DELETE /api/user/stars/dashboard/uid/BqokFhx7z HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```

**Example Response**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
GET /api/user/auth-tokens HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```

**Example Response**:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
HTTP/1.1 200
Content-Type: application/json

{
  "message": "User auth token revoked"
}
```