# 조직 멤버 목록 조회

`GET /fapi/v1/organizations/{org_id}/memberships` · 환경의 로그인 호스트에서 호출

조직 프로필 화면에 사용할 수 있도록 조직의 멤버십을 마지막 변경 순으로 나열합니다. 대기 중인 초대는 여기에 표시되지 않습니다. 각 행은 사용자를 `usr_…` 식별자로만 나타내며, 이 엔드포인트는 이름이나 이메일 주소를 반환하지 않습니다. 인증된 사용자의 `__Host-idp_session` 쿠키가 필요합니다. 쿠키가 없거나 만료되었거나 폐기된 경우 `401 unauthenticated`를 반환합니다. 다른 출처의 자사 앱은 대신 Front API 액세스 토큰(DPoP 증명과 함께 `Authorization: DPoP <token>`)을 보낼 수 있습니다. 자세한 내용은 [Front API 액세스 토큰](/docs/api/fapi/front-api-token)을 참조하세요. 사용자는 `idp_members:read` 권한을 가진 조직의 활성 멤버여야 합니다. 멤버가 아닌 사용자는 `404 not_found`를, 권한이 없는 멤버는 `403 insufficient_permissions`를 받습니다.

`@keenauth/js`를 사용하는 경우: `await keenauth.organizations.members(orgId, { status: "active" })`.

## 요청

헤더:

| 헤더 | 필수 여부 | 설명 |
| --- | --- | --- |
| `Idp-Client` | 예 | SDK 식별자입니다. |

`org_id`: 조직 식별자(`org_…`)입니다.

쿼리 매개변수:

| 매개변수 | 필수 여부 | 설명 |
| --- | --- | --- |
| `status` | 아니요 | `active`, `suspended` 또는 `removed`입니다. 생략하면 세 가지 모두 조회합니다. |
| `role_id` | 아니요 | 이 역할(`rol_…`)을 가진 멤버십만 조회합니다. |
| `after` | 아니요 | 이전 페이지의 `next_after` 값입니다(불투명 값). |
| `limit` | 아니요 | 1~100, 기본값은 20입니다. |

본문은 없습니다.

## 응답

`200 OK`와 함께 `{"data": [...], "next_after": "..."}`를 반환합니다. 마지막 페이지에는 `next_after`가 없습니다.

각 항목: `id`(`mem_…`), `user_id`(`usr_…`), `status`, `roles`(각각 `role_id`와 할당 출처인 `source`를 포함하며, 예: `admin_api` 또는 `default`), `created_at`, `activated_at`(없으면 `null`), `expires_at`(없으면 `null`), `updated_at`, `version`.

## 오류

| 상태 코드 | 코드 | 발생 조건 |
| --- | --- | --- |
| 400 | `invalid_cursor` | `after` 형식이 잘못되었습니다. |
| 401 | `unauthenticated` | 유효한 세션 쿠키가 없습니다. |
| 403 | `insufficient_permissions` | 사용자에게 조직 내 `idp_members:read` 권한이 없습니다. |
| 404 | `not_found` | 이 사용자에 대한 해당 조직이 없습니다. 알 수 없거나 형식이 잘못되었거나 다른 사용자의 식별자도 같은 응답을 받습니다. |
| 422 | `validation_failed` | `status`, `role_id` 또는 `limit`이 잘못되었습니다. |
| 503 | `service_unavailable` | 일시적으로 사용할 수 없습니다. `Retry-After` 이후에 다시 시도하세요. |

## 예시

```bash
curl "https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/memberships?status=active&limit=2" \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -b cookies.txt
```

```json
{
  "data": [
    {
      "id": "mem_01jbz6x8kq3m2n4p5r6s7t8v9b",
      "user_id": "usr_01jbz6x8kq3m2n4p5r6s7t8v9c",
      "status": "active",
      "roles": [{ "role_id": "rol_01jbz6x8kq3m2n4p5r6s7t8v9w", "source": "admin_api" }],
      "created_at": "2026-11-03T09:00:00Z",
      "activated_at": "2026-11-03T09:00:00Z",
      "expires_at": null,
      "updated_at": "2026-11-03T09:00:00Z",
      "version": 1
    }
  ],
  "next_after": "AAAYQ3dAgGUBmgAAAABwAIAAAAAAAADh"
}
```

## 개인정보

이 엔드포인트는 개인정보를 다룹니다. 조직 멤버십과 초대가 해당합니다. [KeenAuth API의 개인정보](/docs/policies/personal-data)에서는 저장되는 정보, 보관 기간, 삭제 방법을 설명합니다. 어떤 필드에도 민감정보(건강, 생체 정보, 종교, 정치적 견해, 성적 지향)를 보내지 마세요.