멤버십 종료일 설정
PATCH /fapi/v1/organizations/{org_id}/memberships/{membership_id} · 환경의 로그인 호스트에서 호출
조직 프로필 화면에서 멤버십이 끝나는 날짜(expires_at)를 설정하거나 해제합니다. 날짜가 지나면 멤버십이 삭제되고, 이 조직 컨텍스트에서 회원의 세션과 토큰이 취소됩니다. 만료 7일 전에는 membership_expiry_warned 이벤트가 발행됩니다. 역할은 회원 역할 설정에서 변경하며, 이 엔드포인트는 종료일만 변경합니다.
인증된 사용자의 __Host-idp_session 쿠키(정확한 Origin 포함) 또는 자사 앱의 Front API 액세스 토큰(DPoP 증명을 포함한 Authorization: DPoP <token>, Front API 액세스 토큰 참조)이 필요합니다. 사용자는 조직의 활성 회원이어야 하며 idp_members:update_roles와 idp_members:remove 권한을 모두 가져야 합니다. 회원이 아닌 사용자는 404 not_found를 받고, 두 권한 중 하나라도 없는 회원은 403 insufficient_permissions를 받습니다. 여기서 본인의 멤버십은 변경할 수 없으며(403 insufficient_permissions), 특권 역할을 가진 회원은 관리자 역할을 가진 사용자만 변경할 수 있습니다(403 role_not_assignable).
@keenauth/js 사용 시: await keenauth.organizations.setMemberExpiry(orgId, membershipId, "2027-03-31T00:00:00Z", { expectedVersion: 3 }). 날짜를 해제하려면 null을 전달하십시오.
요청
헤더:
| 헤더 | 필수 여부 | 설명 |
|---|---|---|
Idp-Client |
예 | SDK 식별자입니다. |
Origin |
쿠키 사용 시 예 | https://<sign-in host>. |
If-Match |
아니요 | 회원 목록에서 읽은 버전 하나, "<version>"입니다. 일치하지 않는 버전이거나 버전이 둘 이상이면 412 precondition_failed를 반환합니다. |
org_id: 조직 식별자(org_…)입니다. membership_id: 멤버십 식별자(mem_…)입니다.
본문: {"expires_at": "<RFC 3339 시각>"} 또는 날짜를 해제하려면 {"expires_at": null}. expires_at은 필수입니다. 시각은 미래여야 하며, 멤버십 생성 후 최대 365일 이내여야 합니다.
응답
멤버십(위 회원 목록의 항목과 같은 필드)과 함께 200 OK, ETag: "<version>"을 반환합니다.
오류
| 상태 | 코드 | 발생 조건 |
|---|---|---|
| 400 | unknown_field |
본문에 expires_at 외의 필드가 있습니다. |
| 400 | malformed_request |
If-Match 형식이 잘못되었습니다. |
| 401 | unauthenticated |
유효한 세션 쿠키나 토큰이 없습니다. |
| 403 | insufficient_permissions |
사용자에게 idp_members:update_roles 또는 idp_members:remove 권한이 없거나, 본인의 멤버십입니다. |
| 403 | role_not_assignable |
회원이 특권 역할을 가지고 있고 사용자에게 관리자 역할이 없습니다. |
| 403 | origin_not_allowed |
Origin이 일치하지 않습니다. |
| 404 | not_found |
이 사용자에게 해당 조직이나 멤버십이 없습니다. 알 수 없거나 형식이 잘못되었거나 다른 조직의 식별자도 같은 응답을 받습니다. |
| 409 | organization_disabled |
조직이 비활성화되었거나 삭제 대기 중입니다(organization_pending_deletion). |
| 412 | precondition_failed |
If-Match가 멤버십의 현재 버전을 가리키지 않습니다. |
| 422 | validation_failed |
expires_at이 없거나, RFC 3339 시각이 아니거나, 과거이거나, 멤버십 생성 후 365일을 초과합니다. |
| 503 | service_unavailable |
일시적으로 사용할 수 없습니다. Retry-After 이후에 다시 시도하십시오. |
예시
curl -X PATCH "https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/memberships/mem_01jbz6x8kq3m2n4p5r6s7t8v9b" \
-H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
-H "Origin: https://example.keenauth.app" \
-H 'If-Match: "3"' \
-H "Content-Type: application/json" \
-b cookies.txt \
-d '{"expires_at": "2027-03-31T00:00:00Z"}'
{
"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",
"updated_at": "2026-11-03T11:00:00Z",
"version": 4
}
개인정보
이 엔드포인트는 조직 멤버십과 초대에 관한 개인정보를 다룹니다. KeenAuth API의 개인정보에서 저장되는 항목, 보관 기간, 삭제 방법을 확인하십시오. 어떤 필드에도 특수 범주의 개인정보(건강, 생체 정보, 종교, 정치적 견해, 성적 지향)를 보내지 마십시오.