조직(Organization) API

조직(Organization) API

조직 HTTP API는 /api/org(현재 조직)와 /api/orgs(관리자 조직) 두 가지 리소스로 나뉘어요. 이 둘의 큰 차이점 중 하나는 모든 조직의 관리자 API가 기본 인증(basic authentication)에서만 동작한다는 것이에요. 자세한 내용은 Admin Organizations API를 참조해요.

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

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

출처: 문서

본문

현재 조직 엔드포인트

Method	Summary	URI
GET	현재 조직 가져오기	/api/org/
GET	현재 조직 내 모든 사용자 가져오기	/api/org/users
GET	현재 조직 내 모든 사용자 가져오기 (조회)	/api/org/users/lookup
PATCH	주어진 사용자 업데이트	/api/org/users/:userId
DELETE	현재 조직에서 사용자 삭제	/api/org/users/:userId
PUT	현재 조직 업데이트	/api/org
POST	현재 조직에 새 사용자 추가	/api/org/users

관리자 조직 엔드포인트

Method	Summary	URI
GET	Id로 조직 가져오기	/api/orgs/:orgId
GET	이름으로 조직 가져오기	/api/orgs/name/:orgName
POST	조직 생성	/api/orgs
GET	모든 조직 검색	/api/orgs
PUT	조직 업데이트	/api/orgs/:orgId
DELETE	조직 삭제	/api/orgs/:orgId
GET	조직 내 사용자 가져오기	/api/orgs/:orgId/users
POST	조직에 사용자 추가	/api/orgs/:orgId/users
PATCH	조직 내 사용자 업데이트	/api/orgs/:orgId/users/:userId
DELETE	조직 내 사용자 삭제	/api/orgs/:orgId/users/:userId

현재 조직 API

현재 조직 가져오기

GET /api/org/

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

Action	Scope
orgs:read	N/A

예제 요청:

GET /api/org/ HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "name":"Main Org."
}

현재 조직 내 모든 사용자 가져오기

GET /api/org/users

현재 조직 내 모든 조직 사용자를 반환해요. 조직 admin 역할이 있는 사용자에게 접근 가능해요.

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

Action	Scope
org.users:read	users:*

예제 요청:

GET /api/org/users HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "orgId": 1,
    "userId": 1,
    "email": "admin@localhost",
    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56",
    "login": "admin",
    "role": "Admin",
    "lastSeenAt": "2019-08-09T11:02:49+02:00",
    "lastSeenAtAge": "< 1m"
  }
]

현재 조직 내 모든 사용자 가져오기 (조회)

GET /api/org/users/lookup

현재 조직 내 모든 조직 사용자를 반환하되, 덜 상세한 정보를 포함해요. 조직 admin 역할이 있거나, 어떤 폴더의 admin이거나, 어떤 팀의 admin인 사용자에게 접근 가능해요. 주로 Grafana UI가 팀 구성원을 추가하거나 폴더/대시보드 권한을 편집할 때 사용자 목록을 제공하는 데 사용돼요.

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

Action	Scope
org.users:read	users:*

예제 요청:

GET /api/org/users/lookup HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "userId": 1,
    "login": "admin",
    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
  }
]

주어진 사용자 업데이트

PATCH /api/org/users/:userId

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

Action	Scope
org.users:write	users:*

예제 요청:

PATCH /api/org/users/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

{
  "role": "Viewer",
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization user updated"}

현재 조직에서 사용자 삭제

DELETE /api/org/users/:userId

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

Action	Scope
org.users:remove	users:*

예제 요청:

DELETE /api/org/users/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"User removed from organization"}

현재 조직 업데이트

PUT /api/org

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

Action	Scope
orgs:write	N/A

예제 요청:

PUT /api/org HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

{
  "name":"Main Org."
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization updated"}

현재 조직에 새 사용자 추가

POST /api/org/users

현재 조직에 글로벌 사용자를 추가해요.

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

Action	Scope
org.users:add	users:*

예제 요청:

POST /api/org/users HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

{
  "role": "Admin",
  "loginOrEmail": "admin"
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"User added to organization","userId":1}

관리자 조직 API

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

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

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

Id로 조직 가져오기

GET /api/orgs/:orgId

기본 인증(사용자 이름과 비밀번호)에서만 동작해요. 서문 참조.

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

Action	Scope
orgs:read	N/A

예제 요청:

GET /api/orgs/1 HTTP/1.1
Accept: application/json
Content-Type: application/json

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "name":"Main Org.",
  "address":{
    "address1":"",
    "address2":"",
    "city":"",
    "zipCode":"",
    "state":"",
    "country":""
  }
}

이름으로 조직 가져오기

GET /api/orgs/name/:orgName

기본 인증(사용자 이름과 비밀번호)에서만 동작해요. 서문 참조.

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

Action	Scope	Note
orgs:read	N/A	전역으로 할당되어야 함.

예제 요청:

GET /api/orgs/name/Main%20Org%2E HTTP/1.1
Accept: application/json
Content-Type: application/json

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "name":"Main Org.",
  "address":{
    "address1":"",
    "address2":"",
    "city":"",
    "zipCode":"",
    "state":"",
    "country":""
  }
}

조직 생성

POST /api/orgs

기본 인증(사용자 이름과 비밀번호)에서만 동작해요. 서문 참조.

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

Action	Scope	Note
orgs:create	N/A	전역으로 할당되어야 함.

예제 요청:

POST /api/orgs HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "name":"New Org."
}

참고: 이 API는 다음 두 가지 방식으로 동작해요.

• GF_USERS_ALLOW_ORG_CREATE=true를 설정해야 함
• ini 파일에 users.allow_org_create 구성 값을 true로 설정

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "orgId":"1",
  "message":"Organization created"
}

모든 조직 검색

GET /api/orgs?perpage=10&page=1

기본 인증(사용자 이름과 비밀번호)에서만 동작해요. 서문 참조.

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

Action	Scope	Note
orgs:read	N/A	전역으로 할당되어야 함.

예제 요청:

GET /api/orgs HTTP/1.1
Accept: application/json
Content-Type: application/json

참고: 이 API는 요청 HTTP URL에 admin 이름과 비밀번호를 전달할 때만 동작해요. 예: http://admin:admin@localhost:3000/api/orgs

perpage 매개변수의 기본값은 1000, page 매개변수의 기본값은 0이에요.

예제 응답:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id":1,
    "name":"Main Org."
  }
]

조직 업데이트

PUT /api/orgs/:orgId

조직을 업데이트해요. Address 1, Address 2, City 필드는 아직 구현되지 않았어요. 기본 인증(사용자 이름과 비밀번호)에서만 동작해요. 서문 참조.

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

Action	Scope
orgs:write	N/A

예제 요청:

PUT /api/orgs/1 HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "name":"Main Org 2."
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization updated"}

조직 삭제

DELETE /api/orgs/:orgId

기본 인증(사용자 이름과 비밀번호)에서만 동작해요. 서문 참조.

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

Action	Scope
orgs:delete	N/A

예제 요청:

DELETE /api/orgs/1 HTTP/1.1
Accept: application/json

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization deleted"}

조직 내 사용자 가져오기

GET /api/orgs/:orgId/users

기본 인증(사용자 이름과 비밀번호)에서만 동작해요. 서문 참조.

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

Action	Scope
org.users:read	users:*

예제 요청:

GET /api/orgs/1/users HTTP/1.1
Accept: application/json
Content-Type: application/json

참고: 이 API는 요청 HTTP URL에 admin 이름과 비밀번호를 전달할 때만 동작해요. 예: http://admin:admin@localhost:3000/api/orgs/1/users

예제 응답:

HTTP/1.1 200
Content-Type: application/json
[
  {
    "orgId":1,
    "userId":1,
    "email":"[email protected]",
    "login":"admin",
    "role":"Admin"
  }
]

조직에 사용자 추가

POST /api/orgs/:orgId/users

기본 인증(사용자 이름과 비밀번호)에서만 동작해요. 서문 참조.

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

Action	Scope
org.users:add	users:*

예제 요청:

POST /api/orgs/1/users HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "loginOrEmail":"user",
  "role":"Viewer"
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"User added to organization", "userId": 1}

조직 내 사용자 업데이트

PATCH /api/orgs/:orgId/users/:userId

기본 인증(사용자 이름과 비밀번호)에서만 동작해요. 서문 참조.

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

Action	Scope
org.users:write	users:*

예제 요청:

PATCH /api/orgs/1/users/2 HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "role":"Admin"
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization user updated"}

조직 내 사용자 삭제

DELETE /api/orgs/:orgId/users/:userId

기본 인증(사용자 이름과 비밀번호)에서만 동작해요. 서문 참조.

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

Action	Scope
org.users:remove	users:*

예제 요청:

DELETE /api/orgs/1/users/2 HTTP/1.1
Accept: application/json
Content-Type: application/json

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"User removed from organization"}

더 알아보기 (Learn more)

• 조직 및 사용자 관리
• 서비스 계정과 토큰
• Grafana의 새 API 구조