Menu

Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentationbreadcrumb arrow Grafana documentationbreadcrumb arrow HTTP APIbreadcrumb arrow User HTTP API
Enterprise Open source

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

[
  {
    "id": 1,
    "name": "Admin",
    "login": "admin",
    "email": "admin@mygraf.com",
    "isAdmin": true
  },
  {
    "id": 2,
    "name": "User",
    "login": "user",
    "email": "user@mygraf.com",
    "isAdmin": false
  }
]

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
{
  "totalCount": 2,
  "users": [
    {
      "id": 1,
      "name": "Admin",
      "login": "admin",
      "email": "admin@mygraf.com",
      "isAdmin": true
    },
    {
      "id": 2,
      "name": "User",
      "login": "user",
      "email": "user@mygraf.com",
      "isAdmin": false
    }
  ],
  "page": 1,
  "perPage": 10
}

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

{
  "email": "user@mygraf.com"
  "name": "admin",
  "login": "admin",
  "theme": "light",
  "orgId": 1,
  "isGrafanaAdmin": true
}

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

{
  "email": "user@mygraf.com",
  "name": "admin",
  "login": "admin",
  "theme": "light",
  "orgId": 1,
  "isGrafanaAdmin": true
}

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=

{
  "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 Organisations 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

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

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

{
  "email":"admin@mygraf.com",
  "name":"Admin",
  "login":"admin",
  "theme":"light",
  "orgId":1,
  "isGrafanaAdmin":true
}

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

{
  "oldPassword": "old_password",
  "newPassword": "new_password",
  "confirmNew": "confirm_new_password"
}

Example Response:

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

{"message":"User password changed"}

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

{"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 
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"}

Organisations of the actual User

GET /api/user/orgs

Return a list of all organisations 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

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

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

{"message":"Dashboard starred!"}

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

{"message":"Dashboard unstarred"}