멤버 API

팀 좌석과 역할을 관리합니다 — 계정의 발급자, 배지, 수여 내역을 함께 사용하는 사람들입니다.

모든 엔드포인트에는 인증이 필요합니다. 인증을 참조하세요. 모든 요청은 인증된 소유자의 계정 범위로 한정됩니다.

API를 통해 할당할 수 있는 역할은 admin, editor, viewer입니다. owner 역할은 계정 보유자를 위해 예약되어 있으며 할당하거나 제거할 수 없습니다.

멤버 목록 조회

계정의 모든 멤버와 대기 중인 초대를 가져옵니다.

GET /members

예시

curl -X GET https://api.badges.ninja/members \
  -H "X-Api-Key: bws_your_api_key_here"

응답

{
  "items": [
    {
      "memberId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "owner@acme.example.com",
      "role": "owner",
      "status": "active"
    },
    {
      "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "email": "editor@acme.example.com",
      "role": "editor",
      "status": "pending"
    }
  ]
}

status는 수락한 멤버의 경우 active, 아직 수락하지 않은 초대의 경우 pending입니다.

---

멤버 초대

이메일로 계정에 사람을 초대합니다. 수락 링크가 담긴 초대 이메일이 해당 주소로 발송됩니다.

POST /members

매개변수

매개변수	유형	필수	설명
email	string	예	초대할 이메일 주소(유효한 이메일이어야 함)
role	string	예	할당할 역할 — admin, editor, viewer 중 하나

예시

curl -X POST https://api.badges.ninja/members \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "email": "editor@acme.example.com",
      "role": "editor"
    }
  }'

응답

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "inviteId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "pending"
}

오류

• 400 — role must be one of admin, editor, viewer
• 400 — 이메일 주소가 잘못되었거나 누락됨
• 400 — seat limit reached — 계정에 해당 요금제의 여유 좌석이 없습니다(Free: 2, Starter: 5, Pro: 20, 소유자 포함). 멤버를 제거하거나 요금제를 업그레이드하세요.
• 400 — 해당 이메일이 이미 이 계정의 멤버이거나 대기 중인 초대가 있음

---

초대 수락

대기 중인 초대를 수락합니다. 인증된 사용자의 이메일은 초대장이 발송된 주소와 일치해야 합니다.

POST /members/accept

매개변수

매개변수	유형	필수	설명
inviteId	string	예	수락 링크 이메일에 담긴 초대 ID

예시

curl -X POST https://api.badges.ninja/members/accept \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "inviteId": "c3d4e5f6-a7b8-9012-cdef-123456789012"
    }
  }'

응답

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "active"
}

오류

• 400 — email does not match invitation — 로그인한 이메일이 초대된 이메일과 다름
• 404 — 초대를 찾을 수 없음(이미 수락 또는 취소되었거나 inviteId가 잘못됨)

---

멤버 역할 업데이트

기존 멤버의 역할을 변경합니다. 소유자 또는 관리자 권한이 필요합니다.

POST /members/{memberId}/role

매개변수

매개변수	유형	필수	설명
memberId	string	예	멤버 ID(경로 매개변수)
role	string	예	새 역할 — admin, editor, viewer 중 하나

예시

curl -X POST https://api.badges.ninja/members/b2c3d4e5-f6a7-8901-bcde-f12345678901/role \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "role": "admin"
    }
  }'

응답

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "role": "admin",
  "updated": true
}

오류

• 400 — role must be one of admin, editor, viewer
• 400 — the owner role cannot be changed
• 404 — 멤버를 찾을 수 없음

---

멤버 제거

멤버를 계정에서 제거하거나 대기 중인 초대를 취소합니다. 멤버는 즉시 액세스 권한을 잃고 그 좌석은 확보됩니다.

DELETE /members/{memberId}

예시

curl -X DELETE https://api.badges.ninja/members/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

응답

단순 문자열:

"member has been removed"

오류

• 400 — the owner cannot be removed
• 404 — 멤버를 찾을 수 없음