baron-sso/docs/integrations-org-context-json-api.md

조직 Context JSON API 계약

목적

외부 연동앱이 계정 세션 없이 M2M 방식으로 Baron SSO의 조직구성을 조회할 수 있게 한다. 조직구성과 사용자 멤버 정보는 Ory SSOT에서 웜업한 Redis cache 또는 Ory Admin API fallback을 기준으로 제공한다. Backend DB users나 claim output을 SSOT 또는 read model로 사용하지 않으며, iframe 또는 postMessage 계약은 사용하지 않는다.

인증

API Key 기반 headless 통신만 허용한다.

X-Baron-Key-ID: <client id>
X-Baron-Key-Secret: <client secret>

필요 scope는 다음과 같다.

org-context:read

API Key 발급/회수는 사람의 관리 행위이므로 super admin 권한으로만 수행한다. 반면 아래 조직 Context 조회 API는 사용자 세션 없이 API Key만으로 동작한다.

Endpoint

GET /api/v1/integrations/org-context

Query

이름	기본값	설명
tenantSlug	hanmac-family	조회할 subtree root tenant slug. 지정하지 않으면 hanmac-family 전체 subtree를 반환한다.
includeUsers	true	false이면 각 tenant의 members를 빈 배열로 반환한다.
includeUserIds	false	true이면 각 tenant의 members[].id와 members[].phone만 추가한다. 사용자 UUID와 전화번호가 필요한 연동에서만 사용한다.

상위 조직 지정은 slug만 사용한다. UUID 기반 지정은 계약에 포함하지 않는다.

예시 요청

curl 'https://sso.example.com/api/v1/integrations/org-context?tenantSlug=hanmac&includeUsers=true' \
  -H 'X-Baron-Key-ID: 01970f08-91da-7286-bd19-882fb98d1f2c' \
  -H 'X-Baron-Key-Secret: <secret>'

예시 응답

{
  "schemaVersion": "baron.org-context.v1",
  "issuedAt": "2026-05-13T12:00:00Z",
  "scope": {
    "tenantId": "01970f08-91da-7286-bd19-882fb98d1f2c",
    "tenantSlug": "hanmac"
  },
  "tree": {
    "id": "01970f08-91da-7286-bd19-882fb98d1f2c",
    "type": "COMPANY",
    "name": "한맥기술",
    "slug": "hanmac",
    "parentId": "01970f07-4f01-7d9a-a71e-b53ad508f345",
    "status": "active",
    "description": "",
    "domains": [],
    "memberCount": 0,
    "visibility": "public",
    "createdAt": "2026-05-13T00:00:00Z",
    "updatedAt": "2026-05-13T00:00:00Z",
    "members": [],
    "children": [
      {
        "id": "01970f09-2b7b-7f83-b9d6-4f6c8b33f01a",
        "type": "USER_GROUP",
        "name": "플랫폼실",
        "slug": "platform",
        "parentId": "01970f08-91da-7286-bd19-882fb98d1f2c",
        "status": "active",
        "description": "",
        "domains": [],
        "memberCount": 0,
        "visibility": "internal",
        "orgUnitType": "실",
        "createdAt": "2026-05-13T00:00:00Z",
        "updatedAt": "2026-05-13T00:00:00Z",
        "members": [
          {
            "email": "user@example.com",
            "name": "홍길동",
            "grade": "책임",
            "position": "실장",
            "jobTitle": "Backend Engineer",
            "isOwner": true,
            "isLeader": true,
            "isPrimary": true
          }
        ],
        "children": []
      }
    ]
  },
  "tenants": [
    {
      "id": "01970f08-91da-7286-bd19-882fb98d1f2c",
      "type": "COMPANY",
      "name": "한맥기술",
      "slug": "hanmac",
      "parentId": "01970f07-4f01-7d9a-a71e-b53ad508f345",
      "status": "active",
      "description": "",
      "domains": [],
      "memberCount": 0,
      "visibility": "public",
      "createdAt": "2026-05-13T00:00:00Z",
      "updatedAt": "2026-05-13T00:00:00Z",
      "members": []
    },
    {
      "id": "01970f09-2b7b-7f83-b9d6-4f6c8b33f01a",
      "type": "USER_GROUP",
      "name": "플랫폼실",
      "slug": "platform",
      "parentId": "01970f08-91da-7286-bd19-882fb98d1f2c",
      "status": "active",
      "description": "",
      "domains": [],
      "memberCount": 0,
      "visibility": "internal",
      "orgUnitType": "실",
      "createdAt": "2026-05-13T00:00:00Z",
      "updatedAt": "2026-05-13T00:00:00Z",
      "members": [
        {
          "email": "user@example.com",
          "name": "홍길동",
          "grade": "책임",
          "position": "실장",
          "jobTitle": "Backend Engineer",
          "isOwner": true,
          "isLeader": true,
          "isPrimary": true
        }
      ]
    }
  ]
}

정책

• tenantSlug가 없으면 hanmac-family 전체 subtree를 반환한다.
• tenantSlug는 slug만 허용한다. UUID를 query 계약으로 쓰지 않는다.
• visibility=private tenant와 그 하위 tenant는 제외한다.
• visibility=internal tenant는 M2M 연동용 JSON API에는 포함한다.
• 외부 앱은 schemaVersion을 확인하고, 알 수 없는 version이면 별도 fallback을 적용한다.
• tree는 같은 tenant 집합을 계층 구조로 제공하고, tenants는 slug/id lookup용 flat array로 제공한다.
• 사용자 목록은 top-level users가 아니라 각 tenant의 members에 직접 소속 사용자 배열로 제공한다.
• members에는 active, temporary_leave, suspended 사용자만 포함한다. preboarding, baron_guest, extended_leave, archived 사용자는 email/local-part 선점 대상일 수 있지만 일반 조직도와 외부 연동 조직 조회에는 노출하지 않는다.
• tenant 세부 분류는 type과 orgUnitType으로 구분한다. orgUnitType은 tenant config.orgUnitType 값이 있을 때만 포함한다.
• 기본 사용자 응답은 로그인 claim 수준의 표시 정보만 제공한다. UUID, role/status, metadata, 생성/수정 시각은 기본 응답에 포함하지 않는다.
• 사용자 UUID와 전화번호가 필요한 연동은 includeUserIds=true를 사용한다. 이때 각 tenant members[].id와 members[].phone만 추가된다.
• isOwner는 appointment metadata의 isOwner 또는 isManager 기준이다.
• isLeader는 appointment metadata의 lead 또는 isLead 기준이며, isOwner/isManager가 true인 경우에도 true로 본다.
• isPrimary는 appointment metadata의 representative, isPrimary, primary 기준이다.
• appointment별 grade, position, jobTitle, department가 있으면 해당 tenant membership 값으로 우선 사용한다.