菜单

开发者

HTTP API

用户 HTTP API

Enterprise Open source

用户 API

注意
您无法使用服务账号令牌对 User HTTP API 进行身份验证。服务账号仅限于一个组织和一个组织角色。它们不能被授予Grafana 服务器管理员权限。
或者，您可以使用Organization HTTP API 和服务账号令牌来管理特定组织中的用户
要使用这些 API 端点，您必须使用基本认证，并且 Grafana 用户必须拥有 Grafana 服务器管理员权限。
默认情况下，Grafana 配置的 admin 用户拥有使用这些 API 端点的权限。

对于 Grafana Cloud 用户，请参阅Organization HTTP API 以查找具有组织管理员角色的用户。

如果您正在运行 Grafana Enterprise，对于某些端点，您需要拥有特定的权限。有关更多信息，请参阅基于角色的访问控制权限。

搜索用户

GET /api/users?perpage=10&page=1&sort=login-asc,email-asc

所需权限

有关解释，请参阅简介中的注释。

操作	范围
users:read	global.users:*

请求示例:

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

perpage 参数的默认值为 1000，page 参数的默认值为 1。需要基本认证，并且认证用户是 Grafana 管理员。

sort 参数是一个可选的逗号分隔的选项列表，用于对搜索结果进行排序。排序过滤器接受的值包括：login-asc、login-desc、email-asc、email-desc、name-asc、name-desc、lastSeenAtAge-asc、lastSeenAtAge-desc。默认情况下，如果未指定 sort，则用户列表将按 login、email 升序排序。

响应示例:

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

所需权限

有关解释，请参阅简介中的注释。

操作	范围
users:read	global.users:*

请求示例:

GET /api/users/search?perpage=10&page=1&query=mygraf HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

perpage 参数的默认值为 1000，page 参数的默认值为 1。响应中的 totalCount 字段可用于用户列表的分页。例如，如果 totalCount 等于 100 个用户，并且 perpage 参数设置为 10，则共有 10 页用户。query 参数是可选的，它将返回 name、login 或 email 字段中包含查询值的结果。带有空格的查询值需要进行 URL 编码，例如 query=Jane%20Doe。

需要基本认证，并且认证用户是 Grafana 管理员。

响应示例:

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
}

按 ID 获取单个用户

GET /api/users/:id

所需权限

有关解释，请参阅简介中的注释。

操作	范围
users:read	global.users:*

请求示例:

GET /api/users/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

需要基本认证，并且认证用户是 Grafana 管理员。

响应示例:

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

按用户名 (login) 或邮箱获取单个用户

GET /api/users/lookup?loginOrEmail=user@mygraf.com

所需权限

有关解释，请参阅简介中的注释。

操作	范围
users:read	global.users:*

使用邮箱作为选项的请求示例:

GET /api/users/lookup?loginOrEmail=user@mygraf.com HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

使用用户名作为选项的请求示例:

GET /api/users/lookup?loginOrEmail=admin HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

需要基本认证，并且认证用户是 Grafana 管理员。

响应示例:

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

所需权限

有关解释，请参阅简介中的注释。

操作	范围
users:write	global.users:*

请求示例:

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

需要基本认证，并且认证用户是 Grafana 管理员。

响应示例:

HTTP/1.1 200
Content-Type: application/json

{"message":"User updated"}

获取用户的组织

GET /api/users/:id/orgs

所需权限

有关解释，请参阅简介中的注释。

操作	范围
users:read	global.users:*

请求示例:

GET /api/users/1/orgs HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

需要基本认证，并且认证用户是 Grafana 管理员。

响应示例:

HTTP/1.1 200
Content-Type: application/json

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

获取用户的团队

GET /api/users/:id/teams

所需权限

有关解释，请参阅简介中的注释。

操作	范围
users:read	global.users:*
teams:read	teams:*

请求示例:

GET /api/users/1/teams HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

需要基本认证，并且认证用户是 Grafana 管理员。

响应示例:

HTTP/1.1 200
Content-Type: application/json

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

用户

当前用户

GET /api/user

请求示例:

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

需要基本认证。

响应示例:

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

修改密码

PUT /api/user/password

更改用户的密码。需要基本认证。

请求示例:

PUT /api/user/password HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

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

响应示例:

HTTP/1.1 200
Content-Type: application/json

{"message":"User password changed"}

使用脚本更改密码

如果您需要使用脚本更改密码，这里有一个使用 curl 和基本认证更改 Admin 密码的示例

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

切换指定用户的用户上下文

POST /api/users/:userId/using/:organizationId

切换用户上下文到指定的组织。需要基本认证，并且认证用户是 Grafana 管理员。

请求示例:

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

响应示例:

HTTP/1.1 200
Content-Type: application/json

{"message":"Active organization changed"}

切换已登录用户的用户上下文

POST /api/user/using/:organizationId

切换用户上下文到指定的组织。

请求示例:

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

响应示例:

HTTP/1.1 200
Content-Type: application/json

{"message":"Active organization changed"}

当前用户的组织

GET /api/user/orgs

返回当前用户的所有组织列表。需要基本认证。

请求示例:

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

响应示例:

HTTP/1.1 200
Content-Type: application/json

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

当前用户所属的团队

GET /api/user/teams

返回当前用户所属的所有团队列表。

请求示例:

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

响应示例:

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/uid/:uid

为当前用户标星指定的仪表盘。

请求示例:

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

响应示例:

HTTP/1.1 200
Content-Type: application/json

{"message":"Dashboard starred!"}

取消标星仪表盘

DELETE /api/user/stars/dashboard/uid/:uid

删除当前用户对指定仪表盘的标星。

请求示例:

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

响应示例:

HTTP/1.1 200
Content-Type: application/json

{"message":"Dashboard unstarred"}

当前用户的认证令牌

GET /api/user/auth-tokens

返回当前用户所有已登录的认证令牌（设备）列表。

请求示例:

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

响应示例:

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

撤销当前用户的指定认证令牌（设备）。该认证令牌（设备）的用户将不再处于登录状态，下次活动时需要重新认证。

请求示例:

POST /api/user/revoke-auth-token HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "authTokenId": 364
}

响应示例:

HTTP/1.1 200
Content-Type: application/json

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

此页是否有帮助？

在 GitHub 中建议编辑

创建 GitHub Issue

发送邮件至 docs@grafana.com

帮助与支持

社区

用户 API

搜索用户

带分页搜索用户

按 ID 获取单个用户

按用户名 (login) 或邮箱获取单个用户

用户更新

获取用户的组织

获取用户的团队

用户

当前用户

修改密码

切换指定用户的用户上下文

切换已登录用户的用户上下文

当前用户的组织

当前用户所属的团队

标星仪表盘

取消标星仪表盘

当前用户的认证令牌

撤销当前用户的认证令牌

此页是否有帮助？

Grafana Labs 相关资源