baron_qa_write/docs/sso_guides/org-context-api.md

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에 연결하려면 조직선택기 통합 가이드의 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, 정확한 response schema는 OpenAPI를 따른다.