# Org Context API Guide

## 목적

외부 조직도·Directory consumer가 Baron의 Tenant subtree와 최소 사용자 projection을 조회하는 계약이다. 자체적인 사용자 연결 기준을 email이나 표시 이름으로 만들지 않는다.

## 호출

- Endpoint: `GET /api/v1/integrations/org-context`
- OperationID: `baron.org-context.read`
- query에 `tenantId` 또는 정책상 허용된 `tenantSlug`를 지정한다.
- credential의 Tenant subtree와 exposure 상한 안에서만 조회한다.

## 식별자

- Tenant와 member의 canonical ID는 UUID다.
- `members[].id`는 Baron canonical identity UUID다.
- email, employee number, name은 표시·검색 속성이며 stable join key가 아니다.
- deprecated email index가 있더라도 merge나 picker selection 기준으로 사용하지 않는다.

## Payload

- response의 Tenant hierarchy와 member projection을 함께 versioned contract로 처리한다.
- 알 수 없는 optional field는 무시하되 required identity field 누락은 실패로 처리한다.
- consumer가 임의로 parent relation이나 Membership을 보정해 쓰지 않는다.
- pagination/cursor가 있으면 모든 page를 수집한 뒤 snapshot 경계를 유지한다.

## 오류와 cache

- scope 밖 Tenant는 `403`으로 처리한다.
- 존재하지 않는 Tenant와 노출되지 않는 Tenant를 client가 권한 추측에 사용하지 않는다.
- projection/readiness 오류를 빈 조직으로 cache하지 않는다.
- cache key에는 Tenant, exposure, API contract version을 포함한다.

API로 받은 데이터를 직접 선택 UI에 연결하려면 [조직선택기 통합 가이드](org-picker-integration.md)의 **Integration API 데이터 + Picker SDK 방식**을 따릅니다. RP Backend가 credential을 보관하고, 브라우저는 `buildOrgChartModel()`과 `renderOrgPicker()`만 사용합니다.

## SDK migration

- v1의 email 중심 join을 UUID 중심 model로 교체한다.
- picker value, selected member, merge key를 모두 UUID로 통일한다.
- compatibility index는 read-only 보조로만 유지한다.
- v1/v2 혼합 배포 시 payload version을 확인하고 silent fallback하지 않는다.

Credential 발급과 회수는 [Directory API Guide](directory-api.md), 정확한 response schema는 OpenAPI를 따른다.