Organization

Organization은 Space들을 담는 최상위 그릇입니다. 회사나 팀 단위가 하나의 Organization에 해당하며, 그 아래에 여러 Space를 둡니다. 구독 플랜(plan)과 멤버십이 Organization 수준에서 관리되므로, 결제와 구성원 권한은 Space가 아니라 이 Organization을 기준으로 적용됩니다.

내가 속한 Organization 목록은 GET /me/organization-memberships로 조회합니다. 이 리소스에는 전체 목록을 반환하는 엔드포인트가 없습니다.

리소스 구조

다음은 Organization "데일리웨어 컴퍼니"의 단일 조회 응답입니다. sys(시스템 속성)와 본문 속성 name·description을 가집니다.

{
  "sys": {
    "id": "ilLRJxDp",
    "type": "Organization",
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-05-11T10:51:16.832Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-05-11T10:51:16.832Z",
    "version": 1,
    "isOfficial": false,
    "plan": { "sys": { "id": "free", "type": "Refer", "targetType": "Plan" } }
  },
  "name": "데일리웨어 컴퍼니",
  "description": "옷·잡화 온라인 쇼핑몰 운영사"
}

주요 키:

  • name: Organization의 이름입니다(1~64자). 회사나 팀의 표시 이름입니다.
  • description: Organization에 대한 설명입니다(1~128자, 선택).
  • plan: 이 Organization의 구독 플랜을 가리키는 Refer<Plan>입니다(예: free). 결제 플랜이 여기에 매여 있습니다.
  • isOfficial: 공식 Organization인지 여부(boolean)입니다.

시스템 속성 (sys)와 본문

모든 Organization은 공통 시스템 속성을 sys 객체에 담습니다. createdBy·updatedBy는 Refer 모양({ "sys": { "id", "type": "Refer", "targetType" } })으로 들어가고, plan은 Refer<Plan>입니다.

속성타입설명
idstring리소스 고유 식별자.
typestring리소스 종류. Organization은 항상 "Organization".
createdByRefer<User>생성한 사용자.
createdAtstring (date-time)생성 시각.
updatedByRefer<User>마지막으로 수정한 사용자.
updatedAtstring (date-time)마지막 수정 시각.
versioninteger (≥1)리소스 버전. 수정할 때마다 1씩 올라갑니다.
isOfficialboolean공식 Organization 여부.
planRefer<Plan>구독 플랜. 예: free.

본문 속성:

속성타입설명
namestring (1~64)Organization 이름. 생성·수정 시 지정합니다.
descriptionstring (1~128)Organization 설명. 선택 항목입니다.
iconstring (읽기) / object (쓰기)Organization 아이콘. 응답에서는 이미지 URL 문자열입니다. 수정 요청에서는 업로드한 파일을 가리키는 객체 { "upload": { "sys": { ..., "targetType": "Upload" } } }로 보냅니다(Upload API로 받은 Upload 참조).
consoleHomeUrlstring (uri)이 Organization에 속한 모든 Space에서 기본 홈 화면을 대신해 표시할 페이지. 콘솔 주소가 아닌 https URL을 지정합니다(조건). 선택 항목입니다.

Organization은 발행 개념이 없는 설정 리소스입니다. 그래서 Content·Media와 달리 sys에 publish·archive·status가 없고, version만 가집니다. version은 Organization을 수정할 때마다 오릅니다.

수정(PUT)은 리소스 전체를 교체하는데, 값을 보내지 않았을 때의 의미가 두 선택 항목에서 서로 반대입니다. icon은 빼면 기존 아이콘이 그대로 유지되지만, consoleHomeUrl은 빼면 저장돼 있던 주소가 지워집니다. 이미 지정한 주소를 유지하려면 수정할 때마다 그 값을 함께 보내야 합니다. 부분 수정(PATCH)은 패치에 적은 속성만 건드리므로, consoleHomeUrl을 지정하지 않으면 그대로 둡니다.

홈 화면에 표시할 페이지의 조건

주소가 저장되었다고 해서 그 페이지가 표시되는 것은 아닙니다. 표시를 거부하는 주소를 지정해도 저장 요청은 성공하고 오류도 반환되지 않으며, 홈 화면에 아무것도 표시되지 않는 것으로만 드러납니다.

그 자리에서 표시되려면 페이지 쪽에 다음이 갖춰져 있어야 합니다.

  • HTTPS로 제공합니다. 콘솔이 HTTPS로 동작하므로, 보안 연결이 아닌 페이지는 브라우저가 표시를 차단합니다.
  • 다른 페이지 안에서의 표시를 허용합니다. 응답 헤더에 Content-Security-Policy: frame-ancestors https://console.weegloo.com을 지정합니다. X-Frame-Options로 표시를 막고 있다면 함께 조정합니다.
  • 쿠키를 사용한다면 SameSite=None; Secure로 발급합니다. 다른 사이트 안에서 표시되는 문맥이므로, 이 표시가 없는 쿠키는 전송되지 않습니다.

페이지는 <iframe> 안에서 표시되며, 그 프레임에는 아래 권한만 열려 있습니다.

속성페이지에서 가능해지는 것
sandbox="allow-scripts"스크립트 실행.
sandbox="allow-same-origin"자기 출처의 쿠키·저장소를 읽고 쓰기, 자기 서버로 요청 보내기.
sandbox="allow-forms"폼 제출.
sandbox="allow-popups"새 창이나 새 탭 열기.
sandbox="allow-popups-to-escape-sandbox"그렇게 열린 창이 이 제한을 물려받지 않기.
sandbox="allow-downloads"파일 다운로드 시작.
sandbox="allow-storage-access-by-user-activation"사용자가 조작했을 때 저장소 접근 권한을 요청하기.
allow="fullscreen"전체 화면 전환.
allow="clipboard-write"클립보드에 쓰기.

여기 없는 것은 동작하지 않습니다. 이때 오류가 발생하지 않고 호출이 조용히 무시되므로, 코드에서는 차단 여부를 알 수 없습니다.

프레임에는 referrerpolicy="strict-origin-when-cross-origin"이 함께 지정됩니다. 그래서 페이지로는 콘솔의 출처까지만 전달되고, 어느 화면에서 열렸는지는 전달되지 않습니다.

sandbox와 별개로, 로그인이 필요한 페이지는 정상적으로 동작하지 않을 수 있습니다. 로그인 제공자 다수가 다른 페이지 안에서의 로그인을 차단하므로 소셜 로그인은 대체로 동작하지 않습니다.

오류

Organization을 다룰 때 만나는 코드입니다. 모든 리소스에 공통인 코드는 공통 오류를 참조하세요.

코드조건
WGL422078요금제가 무료가 아닌 Organization을 삭제하려 했습니다. 먼저 무료 요금제로 내려야 합니다.
WGL422079구독이 해지되지 않았거나 변경이 대기 중인 Organization을 삭제하려 했습니다.
WGL422024Space가 남아 있는 Organization을 삭제하려 했습니다. Space를 모두 지운 뒤에 삭제할 수 있습니다.
WGL422046icon으로 올린 파일이 허용 크기를 넘습니다.
WGL422047icon으로 올린 파일이 PNG·JPG·WebP가 아닙니다.
WGL400072consoleHomeUrl의 형식이 올바르지 않거나 콘솔 주소를 가리켰습니다.

API

아래 모든 엔드포인트의 기준 URL은 https://cma.weegloo.com/v1이며, Authorization 헤더에 CMA를 인증하는 Bearer 토큰이 필요합니다. 수정·부분 수정에는 낙관적 동시성 제어를 위해 X-Weegloo-Version 헤더(현재 리소스의 sys.version)를 함께 보내야 합니다. 생성과 삭제에는 이 헤더가 없습니다.