Space Access Token

Space Access Token 是一种可以在一个 Space 内读取和写入内容的令牌。可以用它通过 CMA 创建、修改、删除内容，CDA 读取和 Upload 也用该令牌调用。签发时会将其绑定到一个 SpaceRole，由该角色决定令牌能做什么、能做到什么程度（可以对哪些 Content Type 执行哪些动作）。

与只读的 Delivery Access Token 不同，该令牌还能写入。而与绑定在整个用户账户上的 Personal Access Token 不同，它只限定于一个 Space，无法访问 Space 设置、组织、账户层面，也无法访问其他 Space。在 CMA 中，Space Access Token 是 Space 的下级资源，路径以 /spaces/{spaceId}/space-access-tokens 为基准。要把该令牌放在服务器上，还是放在公开的客户端（例如匿名写入）上，可根据服务自行决定。由于它是带有写入权限的强力令牌，需按令牌所在位置的暴露范围收窄所绑定的角色来确保安全（参见下文 安全：按暴露范围绑定角色）。

资源结构

下面是创建 Space Access Token 时的响应。sys（系统属性）中包含令牌值和范围，正文中有 name 和 description。

{
  "sys": {
    "id": "7WpR4mKq2bTnXfLc8Vd3HsJ9gEyAo",
    "type": "SpaceAccessToken",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "user": { "sys": { "id": "3trmXRLdJIqc9GPBbyFYQQwYT32LnU", "type": "Refer", "targetType": "User" } },
    "createdBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-19T02:15:38.472Z",
    "updatedBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-19T02:15:38.472Z",
    "accessToken": "SPCATq8Lm2vK9pXfR1Zt0Nc4Wd6Hg5Ua2Ee9Ck3PoYx8Bj6Hg5Ua2Ee9Ck3Po…",
    "scopes": ["SPACE_ACCESS_TOKEN"]
  },
  "description": "服装商城商品登记与修改用的服务器令牌",
  "name": "商品后端服务器"
}

主要键：

• sys.id：Space Access Token 的唯一标识符。用于单条查询、修改、删除路径中的 {spaceAccessTokenId}。
• sys.space：该令牌所属的 Space。令牌只在这一个 Space 中运行。
• sys.accessToken：调用 API 时使用的密钥令牌值。以 SPCAT 开头，签发后再次查询也会原样返回同一个值，因此需注意避免暴露（参见下文安全章节）。
• sys.scopes：令牌的权限范围。Space Access Token 在签发时始终为 ["SPACE_ACCESS_TOKEN"]。
• sys.user：该令牌的权限主体，即其专用用户。在签发时自动创建，所绑定的 SpaceRole 的权限会授予该用户。也就是说，令牌的实际权限来自该用户。它与实际签发该令牌的人（sys.createdBy）是不同的用户。
• name：创建时指定的令牌名称（例如 商品后端服务器）。
• description：对令牌的说明（可选）。

role（要绑定的 SpaceRole）是仅在创建请求正文中发送的输入值，不包含在响应资源中。所绑定的角色是以授予该令牌专用用户（响应中的 sys.user）的方式实现的，因此不会作为 role 字段返回到查询响应中。上例中的 accessToken 是密钥值，因此已替换为示例字符串。实际为一段以 SPCAT 开头的、较长的不透明字符串，签发后再次查询会返回同一个值。

系统属性 (sys)

每个 Space Access Token 都在 sys 对象中包含通用系统属性和令牌专有属性。space、user、createdBy、updatedBy 以 Refer 形式（{ "sys": { "id", "type": "Refer", "targetType" } }）出现。

正文属性：

仅创建请求正文使用的输入：

安全：按暴露范围绑定角色

Space Access Token 是一种连写入都能做的强力令牌。将其绑定到哪个 SpaceRole，就成了该令牌能做之事的边界，也是安全边界。要把该令牌放在服务器上，还是放在公开的客户端（例如匿名写入）上，可根据服务自行决定；安全并不靠"藏在哪里"，而是靠按暴露范围收窄所绑定的角色来确保。

• 在创建请求的 role 中，填入只允许该用途所需动作的、范围狭窄的 SpaceRole 的 sys.id。 比如商品登记用的服务器令牌，就绑定只允许对商品 Content Type 读取和写入的角色；公开的匿名写入令牌，就绑定只允许对帖子 Content Type 创建（create）的角色，按暴露范围做最小化绑定。
• 越是暴露给公开客户端的令牌，越要把角色收得更窄。 只应允许到即使该令牌泄露也能承受的范围。不要把 Administrator 角色或范围宽泛的写入角色绑定到公开令牌上。此外，不要随手使用 SpaceRole 列表中的第一项，而应明确指定预期的、范围狭窄的角色的 sys.id。
• 对于向访问者公开的只读传递，没有写入权限的 Delivery Access Token 更合适。只在需要写入时才使用 Space Access Token，并按暴露范围收窄其角色。
• accessToken 是签发后仍会以同一个值被查询到的密钥值。在无需暴露的地方，不要以明文留在代码、日志、存储或错误消息中；一旦怀疑泄露，就删除以使其失效，并换成新令牌。

（来源：weegloo-space-access-token、weegloo-delivery-access-token 技能，以及 .claude/rules/weegloo-global-rules.md。）

状态与约束

创建、修改时需遵守的值约束。

关于绑定与权限的规则：

• 要绑定的 role 必须确实存在于该 Space 中。若填入不存在的角色的 sys.id，创建会被拒绝（WGL404001）。错误的 spaceId 也会以同一代码失败。
• 调用者只能绑定自己在该 Space 中拥有的角色。这是为了防止通过绑定自己并不拥有的角色而给令牌赋予更高权限的约束，违反时会以 WGL422001 被拒绝。但该 Space 的管理员（持有 Administrator 角色者）不受此约束，可以绑定任何角色。
• Space Access Token 是有数量限额的资源。超出当前方案的签发数量限额时，创建会被拒绝（WGL429001）。各方案的限额请参阅 定价方案。
• 签发与管理（创建、查询、修改、删除）需要该 Space 的 API Key 设置权限。用 Space Access Token 自身无法创建其他 Space Access Token。

API

下面所有端点的基准 URL 均为 https://cma.weegloo.com/v1，并且 Authorization 头中需要用于向 CMA 认证的 Bearer 令牌。修改和部分修改 Space Access Token 时不需要 X-Weegloo-Version 头。

相关文档

• SpaceRole：定义要绑定到该令牌的角色（读取与写入范围）。
• Delivery Access Token：向访问者公开的只读传递令牌（客户端用）。
• Personal Access Token：绑定在整个账户上的、用于服务器与 CI 的 Weegloo User 令牌。
• 定价方案：各方案的 Space Access Token 签发数量限额。