멤버십 API

엔드포인트: /api/iam/memberships/

그룹 멤버십을 관리하여 그룹 내 사용자 역할과 접근 권한을 제어합니다.

멤버십 목록 조회

그룹 멤버십 목록을 가져옵니다. 기본 정렬 순서는 역할순, 그 다음 최근 수정일순입니다.

GET /api/iam/memberships/

쿼리 파라미터

파라미터	타입	설명
`group`	UUID	그룹 ID로 필터링
`user`	UUID	사용자 ID로 필터링
`role`	string	역할로 필터링 (`member`, `manager`, `owner`)
`search`	string	`id`, `role`, `group__name`, `group__display_name`, `user__username`, `user__email` 필드에서 검색
`ordering`	string	정렬 필드. 옵션: `role`, `added_at`, `updated_at`. 내림차순은 `-` 접두사 사용
`page`	integer	페이지 번호
`page_size`	integer	페이지당 결과 수 (기본값: 15, 최대: 100)

응답

{
  "count": 12,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "f16a3d45-7e9f-4b0c-d234-5a6b7c8d9e0f",
      "group": "d94e1b23-5c7d-4f8a-b012-3e4f5a6b7c8d",
      "group_name": "developers",
      "user": {
        "id": "a540bf0f-8b37-4f03-8546-dd71c6b03329",
        "name": "admin",
        "email": "admin@example.com",
        "username": "admin",
        "is_active": true,
        "is_staff": true,
        "is_superuser": true
      },
      "role": "owner"
    }
  ]
}

멤버십 생성

사용자를 그룹에 지정된 역할로 추가합니다. 이 엔드포인트를 통해 기본 “alpacon” 그룹에는 멤버를 추가할 수 없습니다.

POST /api/iam/memberships/

요청 본문

{
  "group": "d94e1b23-5c7d-4f8a-b012-3e4f5a6b7c8d",
  "user": "b651cf10-9c48-4a14-9657-ee82d7c14430",
  "role": "member"
}

요청 파라미터

필드	타입	필수	설명
`group`	UUID	Yes	그룹 ID (기본 “alpacon” 그룹은 사용 불가)
`user`	UUID	Yes	사용자 ID. `{"id": "uuid"}` 객체 형식도 허용
`role`	string	No	역할: `member`, `manager`, 또는 `owner` (기본값: `member`)

역할 계층

역할	설명
`member`	기본 역할. 매니저 또는 소유자가 제거 가능
`manager`	멤버 추가/제거 및 그룹 설정 수정 가능
`owner`	전체 제어 권한. 그룹당 최소 한 명의 소유자 필수

응답

{
  "id": "a27b4e56-8f0a-4c1d-e345-6b7c8d9e0f1a",
  "group": "d94e1b23-5c7d-4f8a-b012-3e4f5a6b7c8d",
  "group_name": "developers",
  "user": {
    "id": "b651cf10-9c48-4a14-9657-ee82d7c14430",
    "name": "jsmith",
    "email": "jane.smith@example.com",
    "username": "jsmith",
    "is_active": true,
    "is_staff": false,
    "is_superuser": false
  },
  "role": "member"
}

멤버십 수정

그룹 내 사용자의 역할을 변경합니다. role 필드만 수정 가능합니다.

PATCH /api/iam/memberships/{membership_id}/

경로 파라미터

파라미터	타입	설명
`membership_id`	UUID	수정할 멤버십의 ID

요청 본문

{
  "role": "manager"
}

요청 파라미터

필드	타입	필수	설명
`role`	string	No	새 역할: `member`, `manager`, 또는 `owner`

응답

{
  "id": "a27b4e56-8f0a-4c1d-e345-6b7c8d9e0f1a",
  "group": "d94e1b23-5c7d-4f8a-b012-3e4f5a6b7c8d",
  "group_name": "developers",
  "user": {
    "id": "b651cf10-9c48-4a14-9657-ee82d7c14430",
    "name": "jsmith",
    "email": "jane.smith@example.com",
    "username": "jsmith",
    "is_active": true,
    "is_staff": false,
    "is_superuser": false
  },
  "role": "manager"
}

멤버십 삭제

그룹에서 사용자를 제거합니다. 그룹에는 항상 최소 한 명의 소유자가 있어야 합니다. 마지막 소유자를 제거하려고 하면 USER_UNIQUE_GROUP_OWNER 오류가 반환됩니다.

DELETE /api/iam/memberships/{membership_id}/

경로 파라미터

파라미터	타입	설명
`membership_id`	UUID	삭제할 멤버십의 ID

응답

204 No Content

그룹에는 항상 최소 한 명의 소유자가 있어야 합니다. 유일한 소유자를 제거하면 오류가 반환됩니다.

오류 코드

상태	오류 코드	설명
400	`INVALID_REQUEST`	잘못된 파라미터
400	`USER_UNIQUE_GROUP_OWNER`	그룹의 마지막 소유자를 제거할 수 없음
401	`UNAUTHORIZED`	인증되지 않음
403	`FORBIDDEN`	권한 거부
404	`NOT_FOUND`	멤버십을 찾을 수 없음