# Directory API Guide

정책 정본은 [Integration Credential 및 Directory API 정책](https://gitea.hmac.kr/baron/baron-sso/wiki/Integration-Credential-%EB%B0%8F-Directory-API-%EC%A0%95%EC%B1%85)이다. 정확한 schema는 Backend OpenAPI를 따른다.

## Credential 준비

1. AdminFront의 API Key 관리에서 Directory 연동 credential을 발급한다.
2. exact OperationID와 concrete Tenant subtree scope를 선택한다.
3. 만료일과 발급 사유를 기록한다.
4. secret은 발급 시 한 번만 안전하게 전달하고 log나 issue에 남기지 않는다.
5. 교체 후 이전 secret이 무효인지 확인한다.

`/admin/*`에 integration credential을 사용하지 않는다. interactive cookie/token과 한 요청에 혼합하지 않는다.

## 사용자 생성

요청 필드, credential 발급, idempotency, 오류 처리와 검증 절차는 [외부 사용자 계정 생성 상세 가이드](integration-directory-user-create-api-guide.md)를 따른다.

- Endpoint: `POST /api/v1/integrations/directory/users`
- OperationID: `directory.user.create`
- credential scope 안의 concrete Tenant를 지정한다.
- identity, status, 허용 profile field만 보낸다.
- System Role, raw Keto relation, protected subtree를 payload로 주입하지 않는다.
- `Idempotency-Key`를 logical create 요청에 결속한다.

timeout 뒤 같은 payload와 idempotency key로 재시도한다. 다른 payload를 같은 key로 보내지 않는다.

## Membership 변경

- Endpoint: `PATCH /api/v1/integrations/directory/users/{userId}/memberships`
- source와 destination이 credential scope에 포함되는지 확인한다.
- add와 remove 대상을 exact UUID로 전달한다.
- representative Tenant 변경이나 계정 삭제를 Membership 변경에 섞지 않는다.

## 오류 처리

- `401`: secret, 만료, revoke 상태 확인
- `403`: OperationID, exposure, Tenant scope 확인
- `409`: idempotency fingerprint 또는 Membership invariant 확인
- `422`: field와 business validation 확인
- `503`: 원장/readiness 장애이므로 사용자를 없다고 처리하지 않음

오류 뒤 새 사용자를 임의 생성하기 전에 기존 idempotency 결과와 대상 identity를 조회한다.

## 운영 종료

1. acceptance용 임시 사용자와 Membership을 명시적으로 정리한다.
2. 임시 credential을 revoke한다.
3. revoked secret으로 호출이 거부되는지 확인한다.
4. audit에서 OperationID, actor, Tenant, 결과가 기록되고 secret이 없는지 확인한다.

조직 조회 연동은 [Org Context API Guide](org-context-api.md)를 따른다.

한맥가족의 기존 사용자 사번·이름·전화번호 수정은 별도 [내부 인사 사용자 정보 수정 가이드](hr-profile-api.md)를 따릅니다. 일반 Directory 키의 접근 범위는 바뀌지 않습니다.