사용자를 조직에 추가

POST /v1/organizations/{org_id}/memberships · 권한 organizations:write

기존 사용자를 조직에 직접 추가합니다(소스 admin_api, 상태 active). role_ids를 지정하지 않으면 조직의 기본 구성원 역할이 부여됩니다. 각 역할은 환경 역할이거나 이 조직의 역할이어야 합니다. 응답에는 ETag가 포함되며, 이 쓰기 작업은 organization_membership.created로 감사 기록됩니다. Idempotency-Key는 선택 사항입니다.

요청

필드 유형 필수 설명
org_id path 예 조직 ID(org_…)입니다.
user_id string 예 사용자 ID(usr_…)입니다.
role_ids string[] 아니요 역할 ID(rol_…)이며, 최대 50개입니다.
expires_at string 아니요 멤버십이 종료되는 미래 시점의 RFC 3339 시간입니다.

응답

멤버십이 포함된 201 Created가 반환됩니다.

{
  "id": "mem_01j9xn5p9s0t4v6w8x0y2z4a6c",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "user_id": "usr_01j9xh2k6p7q1r3s5t7v9w1x3y",
  "status": "active",
  "source": "admin_api",
  "reason": null,
  "roles": [
    {
      "role_id": "rol_01j9xr7s1t2w6x8y0z2a4b6c8e",
      "source": "admin_api",
      "assigned_at": "2026-10-12T09:31:00.123456Z"
    }
  ],
  "expires_at": null,
  "created_at": "2026-10-12T09:31:00.123456Z",
  "activated_at": "2026-10-12T09:31:00.123456Z",
  "suspended_at": null,
  "removed_at": null,
  "updated_at": "2026-10-12T09:31:00.123456Z",
  "version": 1
}

오류

HTTP code 발생 조건
404 not_found 이 환경에 조직 또는 사용자가 없습니다.
403 role_not_assignable 역할이 환경 역할이 아니거나 이 조직의 역할이 아닙니다.
403 user_not_active 사용자가 활성 상태가 아닙니다.
409 membership_already_exists 사용자가 이미 조직의 구성원입니다.
409 organization_disabled 조직이 비활성화되어 있습니다.
409 organization_membership_limit_reached 조직의 멤버십 한도에 도달했습니다.
409 membership_limit_reached 사용자의 멤버십 한도에 도달했습니다.
422 anonymous_user_not_allowed 사용자가 익명 사용자입니다.
422 validation_failed 필드가 없거나 잘못되었습니다.
401 unauthenticated 자격 증명이 없거나, 잘못되었거나, 취소되었습니다.
403 insufficient_permissions 자격 증명에 필요한 권한이 없습니다. 권한이 필요한 역할(is_privileged)을 부여하려면 roles:write도 필요하며, 없으면 아무것도 기록되지 않고 required_permissions에 두 권한이 모두 표시됩니다.
429 rate_limited 요청 한도를 초과했습니다. Retry-After 기간 이후에 다시 시도하십시오.
503 service_unavailable 종속 서비스를 일시적으로 사용할 수 없습니다. Retry-After 기간 이후에 다시 시도하십시오.

예시

curl -i -X POST "https://api.eu.keenauth.com/v1/organizations/org_01j9xk3m7q8r2s4t6v8w0y2z4a/memberships" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"usr_01j9xh2k6p7q1r3s5t7v9w1x3y","role_ids":["rol_01j9xr7s1t2w6x8y0z2a4b6c8e"]}'

개인정보

이 엔드포인트는 개인정보를 다룹니다. 조직 멤버십과 초대가 해당합니다. KeenAuth API의 개인정보에서 저장되는 항목, 보관 기간, 삭제 방식을 설명합니다. 어떤 필드에도 특수 범주의 개인정보(건강, 생체 정보, 종교, 정치적 견해, 성적 지향)를 보내지 마십시오.