사용자(User) API

사용자(User) API

⚠️ 서비스 계정 토큰으로 User HTTP API에 인증할 수 없어요. 서비스 계정은 조직과 조직 역할로 제한돼요. 서비스 계정에는 Grafana 서버 관리자 권한을 부여할 수 없어요.

대신 서비스 계정 토큰으로 Organization HTTP API를 사용해 특정 조직의 사용자를 관리할 수 있어요.

이 API 엔드포인트를 사용하려면 기본 인증을 사용해야 하고, Grafana 사용자에게 Grafana 서버 관리자 권한이 있어야 해요.

Grafana가 기본으로 프로비저닝하는 admin 사용자는 이 API 엔드포인트를 사용할 권한이 있어요.

Grafana Cloud 고객은 org Admin 역할이 있는 사용자를 찾으려면 Organization HTTP API를 참조해요.

⚠️ Grafana 13부터 /api 엔드포인트가 /apis 라우트로 대체되어 더 이상 사용되지 않게(deprecated) 되고 있어요. Grafana가 기존 API를 마이그레이션하는 동안 현재 사용 중인 레거시 API와 정확히 일치하지 않을 수 있어요. 이 변경으로 현재 설정이 중단되거나 깨지지는 않아요. 레거시 API는 비활성화되지 않으며 완전히 접근·사용 가능하지만, /api 라우트는 더 이상 업데이트되지 않아요. 자세한 내용은 "Grafana의 새 API 구조" 문서를 참조해요.

Grafana Enterprise를 사용 중이라면 일부 엔드포인트에 특정 권한이 필요해요. 자세한 내용은 "Role-based access control permissions" 문서를 참조해요.

출처: 문서

본문

사용자 검색

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

필요한 권한 — 서문의 참고를 참조해요.

Action	Scope
users:read	global.users:*

예제 요청:

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

perpage 매개변수의 기본값은 1000, page 매개변수의 기본값은 1이에요. 기본 인증과 인증된 사용자가 Grafana Admin이어야 해요.

sort 매개변수는 검색 결과를 정렬할 선택적 쉼표 구분 목록이에요. 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": "[email protected]",
    "isAdmin": true,
    "isDisabled": false,
    "lastSeenAt": "2020-04-10T20:29:27+03:00",
    "lastSeenAtAge": "2m",
    "authLabels": ["OAuth"]
  },
  {
    "id": 2,
    "name": "User",
    "login": "user",
    "email": "[email protected]",
    "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

필요한 권한 — 서문의 참고를 참조해요.

Action	Scope
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 YWRtaW...=

perpage 매개변수의 기본값은 1000, page 매개변수의 기본값은 1이에요. 응답의 totalCount 필드는 사용자 목록의 페이지네이션에 사용할 수 있어요. 예를 들어 totalCount가 100명이고 perpage가 10이면 사용자 페이지는 10개예요. query 매개변수는 선택 사항이며, query 값이 name, login 또는 email 필드 중 하나에 포함된 결과를 반환해요. 공백이 있는 query 값은 URL 인코딩해야 해요. 예: query=Jane%20Doe.

sort 매개변수는 검색 결과를 정렬할 선택적 쉼표 구분 목록이에요. sort 필터에 허용되는 값: login-asc, login-desc, email-asc, email-desc, name-asc, name-desc, lastSeenAtAge-asc, lastSeenAtAge-desc. 기본적으로 sort를 지정하지 않으면 사용자 목록은 login, email 오름차순으로 정렬돼요.

기본 인증과 인증된 사용자가 Grafana Admin이어야 해요.

예제 응답:

HTTP/1.1 200
Content-Type: application/json
{
  "totalCount": 2,
  "users": [
    {
      "id": 1,
      "name": "Admin",
      "login": "admin",
      "email": "[email protected]",
      "isAdmin": true,
      "isDisabled": false,
      "lastSeenAt": "2020-04-10T20:29:27+03:00",
      "lastSeenAtAge': "2m",
      "authLabels": ["OAuth"]
    },
    {
      "id": 2,
      "name": "User",
      "login": "user",
      "email": "[email protected]",
      "isAdmin": false,
      "isDisabled": false,
      "lastSeenAt": "2020-01-24T12:38:47+02:00",
      "lastSeenAtAge": "2M",
      "authLabels": []
    }
  ],
  "page": 1,
  "perPage": 10
}

Id로 단일 사용자 가져오기

GET /api/users/:id

필요한 권한 — 서문의 참고를 참조해요.

Action	Scope
users:read	global.users:*

예제 요청:

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

기본 인증과 인증된 사용자가 Grafana Admin이어야 해요.

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "id": "1",
  "email": "[email protected]",
  "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/[email protected]

필요한 권한 — 서문의 참고를 참조해요.

Action	Scope
users:read	global.users:*

이메일을 옵션으로 사용하는 예제 요청:

GET /api/users/[email protected] HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW...=

사용자 이름을 옵션으로 사용하는 예제 요청:

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

기본 인증과 인증된 사용자가 Grafana Admin이어야 해요.

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "email": "[email protected]",
  "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

필요한 권한 — 서문의 참고를 참조해요.

Action	Scope
users:write	global.users:*

예제 요청:

PUT /api/users/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic ***

{
  "email":"[email protected]",
  "name":"User2",
  "login":"user",
  "theme":"light"
}

기본 인증과 인증된 사용자가 Grafana Admin이어야 해요.

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"User updated"}

사용자의 조직 가져오기

GET /api/users/:id/orgs

필요한 권한 — 서문의 참고를 참조해요.

Action	Scope
users:read	global.users:*

예제 요청:

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

기본 인증과 인증된 사용자가 Grafana Admin이어야 해요.

예제 응답:

HTTP/1.1 200
Content-Type: application/json

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

사용자의 팀 가져오기

GET /api/users/:id/teams

필요한 권한 — 서문의 참고를 참조해요.

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

예제 요청:

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

기본 인증과 인증된 사용자가 Grafana Admin이어야 해요.

예제 응답:

HTTP/1.1 200
Content-Type: application/json

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

실제 사용자 (Actual User)

실제 사용자

GET /api/user

예제 요청:

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

기본 인증이 필요해요.

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "email":"[email protected]",
  "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 ***

{
  "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 Admin이어야 해요.

예제 요청:

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

예제 응답:

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

예제 응답:

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 YWRtaW...=

예제 응답:

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

예제 응답:

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

실제 사용자에 대해 주어진 대시보드를 즐겨찾기(star) 처리해요.

예제 요청:

POST /api/user/stars/dashboard/uid/BqokFhx7z HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

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

예제 응답:

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

예제 응답:

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 <SERVI...KEN>

{
  "authTokenId": 364
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

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

더 알아보기 (Learn more)

• 사용자 및 조직 관리
• 조직 HTTP API
• Grafana의 새 API 구조