Organization

Organization 是承载多个 Space 的顶层容器。一家公司或一个团队对应一个 Organization，其下可以放置多个 Space。订阅套餐（plan）和成员关系在 Organization 层级管理，因此计费和成员权限都以该 Organization 为基准应用，而不是以 Space 为基准。

可以通过 GET /me/organization-memberships 查询当前用户所属的 Organization 列表。该资源没有返回全部列表的端点。

资源结构

下面是 Organization「DailyWear 公司」单条查询的响应。它包含 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": "DailyWear 公司",
  "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。每次修改 Organization 时 version 都会递增。

修改（PUT）会替换整个资源，而两个可选项在不发送值时的含义正好相反。省略 icon 时原有图标会保持不变，但省略 consoleHomeUrl 时已保存的地址会被清除。要保留已经指定的地址，每次修改都必须一并发送该值。部分修改（PATCH）只会改动补丁中写到的属性，因此只要不指定 consoleHomeUrl，就会保持原样。

在主页上显示的页面需要满足的条件

地址保存成功并不代表该页面就会显示出来。即使指定了拒绝被显示的地址，保存请求依然会成功，也不会返回错误，唯一的表现就是主页上什么都不显示。

要在那个位置显示出来，页面一侧需要具备以下条件。

  • 通过 HTTPS 提供页面。 控制台运行在 HTTPS 上，因此浏览器会阻止非安全连接的页面在其中显示。
  • 允许在其他页面内部显示。 在响应头中指定 Content-Security-Policy: frame-ancestors https://console.weegloo.com。如果正在用 X-Frame-Options 阻止显示，请一并调整。
  • 如果使用 Cookie，请以 SameSite=None; Secure 签发。 由于是在其他站点内部显示的上下文，没有该标记的 Cookie 不会被发送。

页面在 <iframe> 内显示，而该框架上只开放了下面这些权限。

属性页面因此能做的事
sandbox="allow-scripts"执行脚本。
sandbox="allow-same-origin"读写自身来源的 Cookie 与存储，向自己的服务器发送请求。
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。必须先把该 Organization 降为免费套餐。
WGL422079试图删除订阅尚未取消、或者变更仍在等待处理的 Organization。
WGL422024试图删除仍有 Space 存在的 Organization。删除全部 Space 之后才能删除该 Organization。
WGL422046作为 icon 上传的文件超出了允许的大小。
WGL422047作为 icon 上传的文件不是 PNG、JPG 或 WebP 格式。
WGL400072consoleHomeUrl 的格式不正确，或者指向了控制台地址。

API

以下所有端点的基准 URL 均为 https://cma.weegloo.com/v1，并且 Authorization 头需要携带用于认证 CMA 的 Bearer 令牌。修改和部分修改需要同时发送用于乐观并发控制的 X-Weegloo-Version 头（当前资源的 sys.version）。创建和删除不需要此头。