# 조직 기본값 업데이트

`PATCH /v1/organization-defaults` · 권한 `organizations:write`

환경의 조직 기본값을 JSON 병합 패치(`application/merge-patch+json`, RFC 7396)로 업데이트합니다. `If-Match`는 필수입니다. 헤더가 없으면 `428`, 오래된 버전이면 `412`가 반환됩니다. 변경할 필드만 전송하십시오. 변경 사항이 없는 패치는 아무것도 쓰지 않으며 버전도 유지됩니다.

## 요청

| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
| `If-Match` | header | 예 | 마지막으로 읽은 기본값의 `ETag`입니다. 없으면 `428`, 오래된 값이면 `412`입니다. |
| `org_admin_role_id` | string | 아니요 | 조직 관리자에게 부여되는 환경 역할(`rol_…`)입니다. 조직 관리 시스템 권한을 보유해야 하며(`422 permission_reserved`), 활성 관리자가 없는 조직이 생겨서는 안 됩니다(`409 last_org_admin`). `null`일 수 없습니다. |
| `default_member_role_id` | string | 아니요 | 새 조직 구성원에게 부여되는 환경 역할(`rol_…`)입니다. `null`일 수 없습니다. |
| `max_memberships_per_user` | integer | 아니요 | 한 사용자가 속할 수 있는 조직 수이며, 1-1000입니다(기본값 200). `null`일 수 없습니다. |
| `invitation_ttl_days` | integer | 아니요 | 초대가 유효한 일수이며, 1-30입니다(기본값 7). `null`일 수 없습니다. |
| `org_self_service_deletion_grace_days` | integer | 아니요 | 셀프 서비스 조직 삭제가 실행되기까지 기다리는 일수이며, 0-30입니다(기본값 14). `null`일 수 없습니다. |
| `on_org_delete_members` | string | 아니요 | `detach`(기본값): 구성원은 멤버십만 잃습니다. `delete_exclusive_provisioned`: JIT 또는 SCIM을 통해 이 조직에 들어왔고 다른 조직에 속하지 않은 사용자는 삭제 대기열에 추가됩니다. `null`일 수 없습니다. |
| `org_custom_roles_enabled` | boolean | 아니요 | 조직 관리자가 자체 역할을 정의할 수 있게 합니다(기본값 `false`). 조직 역할을 작성하려면 여전히 `org_custom_roles` 요금제 기능이 필요합니다. `null`일 수 없습니다. |
| `org_self_delete_enabled` | boolean | 아니요 | 조직 관리자가 직접 조직을 삭제할 수 있게 합니다(기본값 `false`). `null`일 수 없습니다. |

## 동작

- 역할 필드는 이 환경의 역할을 지정해야 합니다. 조직 역할이거나 알 수 없는 역할이면 `unknown_role` 사유와 함께 `422 validation_failed`가 반환됩니다.
- `on_org_delete_members` 변경은 변경 이후 삭제되는 조직에 적용됩니다.
- 유효성 검사 오류에는 필드의 JSON 포인터가 포함됩니다. 예를 들어 코드 `out_of_range`와 함께 `/invitation_ttl_days`가 반환됩니다.
- 변경 사항은 관리 감사 로그에 `organization_defaults.updated`로 기록되며, 값이 아니라 변경된 필드의 이름만 기록됩니다.

## 응답

업데이트된 기본값과 새 `ETag`가 포함된 `200 OK`가 반환됩니다.

```json
{
  "org_admin_role_id": "rol_01j9xs0a2b4c6d8e0f2g4h6j8k",
  "default_member_role_id": "rol_01j9xs0a2b4c6d8e0f2g4h6j8m",
  "max_memberships_per_user": 200,
  "invitation_ttl_days": 9,
  "org_self_service_deletion_grace_days": 14,
  "on_org_delete_members": "delete_exclusive_provisioned",
  "org_custom_roles_enabled": false,
  "org_self_delete_enabled": false,
  "updated_at": "2026-11-03T10:00:00.123456Z",
  "version": 2
}
```

## 오류

| HTTP | code | 발생 조건 |
|---|---|---|
| 400 | `unknown_field` | 패치에 알 수 없거나 읽기 전용인 필드가 있거나, JSON 객체가 아닙니다(`malformed_request`). |
| 403 | `insufficient_permissions` | 자격 증명에 필요한 권한이 없습니다. |
| 409 | `last_org_admin` | 새 관리자 역할을 적용하면 활성 관리자가 없는 조직이 생깁니다. |
| 412 | `precondition_failed` | `If-Match`가 현재 버전과 일치하지 않습니다. |
| 415 | `unsupported_media_type` | 콘텐츠 유형이 `application/merge-patch+json`이 아닙니다. |
| 422 | `validation_failed` | 값이 잘못되었거나(포인터가 필드를 가리킴), 필드가 `null`로 설정되었습니다(`code: invalid`). |
| 428 | `precondition_required` | `If-Match`가 없습니다. |

## 예시

```bash
curl -i -X PATCH "https://api.eu.keenauth.com/v1/organization-defaults" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "1"' \
  -d '{"on_org_delete_members":"delete_exclusive_provisioned","invitation_ttl_days":9}'
```

```bash
keenauth organization-defaults update --if-match '"1"' \
  --on-org-delete-members delete_exclusive_provisioned --invitation-ttl-days 9
```