회원

조직 회원은 Capgo 조직에 액세스할 수 있는 사용자입니다. 각 회원은 조직 내에서 권한을 결정하는 특정 역할을 가지고 있습니다. 회원을 효과적으로 관리하는 것은 팀의 보안과 협업을 유지하는 데 중요합니다.

회원 역할

일반 역할

• read: 리소스를 볼 수 있지만 변경할 수 없습니다
• upload: 새 번들을 업로드하고 리소스를 볼 수 있습니다
• write: 리소스를 수정하고 번들을 업로드할 수 있습니다
• admin: 조직 설정 및 회원을 관리할 수 있습니다
• super_admin: 조직에 대한 완전한 제어 권한을 가집니다

초대 역할

• invite_read: 읽기 액세스에 대한 대기 중인 초대
• invite_upload: 업로드 액세스에 대한 대기 중인 초대
• invite_write: 쓰기 액세스에 대한 대기 중인 초대
• invite_admin: 관리자 액세스에 대한 대기 중인 초대
• invite_super_admin: 슈퍼 관리자 액세스에 대한 대기 중인 초대

모범 사례

1. 역할 할당: 역할을 할당할 때 최소 권한 원칙을 따르세요
2. 정기 감사: 정기적으로 회원 액세스를 검토하고 사용하지 않는 계정을 제거하세요
3. 온보딩: 새 회원을 추가하고 역할을 할당하는 명확한 프로세스를 가지세요
4. 오프보딩: 조직을 떠나는 회원의 액세스를 즉시 제거하세요

엔드포인트

POST

https://api.capgo.app/organization/members/

조직에 새 회원을 추가하거나 기존 회원의 역할을 업데이트합니다. 이미 Capgo 계정이 있는 사용자만 초대할 수 있습니다 - 이메일은 기존 Capgo 사용자와 일치해야 합니다.

요청 본문

interface MemberCreate {
  orgId: string
  email: string
  role: "read" | "upload" | "write" | "admin" | "super_admin"
}

요청 예시

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "org_123",
    "email": "newmember@example.com",
    "role": "write"
  }' \
  https://api.capgo.app/organization/members/

성공 응답

{
  "status": "OK",
  "data": {
    "uid": "user_789",
    "email": "newmember@example.com",
    "role": "invite_write",
    "image_url": null
  }
}

참고사항:

• 새 회원을 추가하면 초대 이메일을 받게 됩니다. 초대를 수락할 때까지 역할 앞에 “invite_“가 붙습니다.
• 초대받기 전에 사용자는 이미 Capgo 계정이 있어야 합니다. 계정이 없는 경우 먼저 https://console.capgo.app/register/ 에서 계정을 만들어야 합니다

GET

https://api.capgo.app/organization/members/

조직의 모든 회원을 검색합니다.

쿼리 매개변수

interface MemberQuery {
  orgId: string
}

응답 타입

interface Member {
  uid: string;
  email: string;
  image_url: string;
  role: "invite_read" | "invite_upload" | "invite_write" | "invite_admin" | "invite_super_admin" | "read" | "upload" | "write" | "admin" | "super_admin";
}

요청 예시

curl -H "authorization: your-api-key" \
  "https://api.capgo.app/organization/members/?orgId=org_123"

응답 예시

{
  "data": [
    {
      "uid": "user_123",
      "email": "john@example.com",
      "image_url": "https://example.com/avatar.png",
      "role": "admin"
    },
    {
      "uid": "user_456",
      "email": "jane@example.com",
      "image_url": "https://example.com/avatar2.png",
      "role": "write"
    },
    {
      "uid": "user_789",
      "email": "bob@example.com",
      "image_url": null,
      "role": "invite_read"
    }
  ]
}

DELETE

https://api.capgo.app/organization/members/

조직에서 회원을 제거합니다. 이렇게 하면 즉시 액세스 권한이 취소됩니다.

요청 본문

interface MemberDelete {
  orgId: string
  email: string
}

요청 예시

curl -X DELETE \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "org_123",
    "email": "user@example.com"
  }' \
  https://api.capgo.app/organization/members/

성공 응답

{
  "status": "OK"
}

오류 처리

일반적인 오류 시나리오 및 응답:

// 회원을 찾을 수 없음
{
  "error": "Member not found",
  "status": "KO"
}

// 잘못된 역할
{
  "error": "Invalid role specified",
  "status": "KO"
}

// 권한 거부
{
  "error": "Insufficient permissions to manage members",
  "status": "KO"
}

// 마지막 관리자를 제거할 수 없음
{
  "error": "Cannot remove the last admin from the organization",
  "status": "KO"
}

// 잘못된 이메일
{
  "error": "Invalid email format",
  "status": "KO"
}

// 회원이 이미 존재함
{
  "error": "Member already exists in organization",
  "status": "KO"
}

일반적인 사용 사례

1. 팀 확장: 적절한 역할을 가진 새 팀 회원 추가
2. 액세스 제어: 책임이 변경될 때 회원 권한 관리
3. 보안 감사: 회원 목록 및 역할 정기 검토
4. 팀 구조 조정: 조직 변경 시 역할 업데이트