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 和 allowedReferrers。

{
  "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"]
  },
  "allowedReferrers": [],
  "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：对令牌的说明（可选）。
• allowedReferrers：限制该令牌可以从哪些 origin 调用的列表。列表为空时不做限制。上面的示例是从服务器调用的令牌，因此把列表留空了（格式规则和判定方式参见 origin 格式规则和 Referer 判定）。

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。
• 如果是从浏览器调用的令牌，请用 allowedReferrers 把调用位置也一并收窄。 所绑定的角色决定用该令牌能做什么，这个列表则决定可以从哪里调用（参见 Referer 判定）。
• 对于向访问者公开的只读传递，没有写入权限的 Delivery Access Token 更合适。只在需要写入时才使用 Space Access Token，并按暴露范围收窄其角色。
• accessToken 是签发后仍会以同一个值被查询到的密钥值。在无需暴露的地方，不要以明文留在代码、日志、存储或错误消息中；一旦怀疑泄露，就删除以使其失效，并换成新令牌。

状态与约束

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

关于绑定与权限的规则：

• 要绑定的 role 必须确实存在于该 Space 中。若填入不存在的角色的 sys.id，创建会被拒绝。
• 调用者只能绑定自己在该 Space 中拥有的角色。这是为了防止通过绑定自己并不拥有的角色而给令牌赋予更高权限的约束，违反这一点的创建请求会被拒绝。但该 Space 的管理员（持有 Administrator 角色者）不受此约束，可以绑定任何角色。
• Space Access Token 是有数量限额的资源。超出当前方案的签发数量限额时，创建会被拒绝。各方案的限额请参阅 定价方案。
• 签发与管理（创建、查询、修改、删除）要求调用者角色的 settings 中包含 SETTING_SPACE_ACCESS_TOKEN。它与用于签发只读 Delivery Access Token 的 SETTING_DELIVERY_ACCESS_TOKEN 是彼此独立的操作，因此可以只授予传递令牌的签发权限，同时阻止签发该令牌（参见 SpaceRole）。
• 该 API 只能通过控制台登录会话和 Personal Access Token 调用。用 Space Access Token 自身无法创建其他 Space Access Token，即使在其绑定的角色中放入 SETTING_SPACE_ACCESS_TOKEN 也是如此。

origin 格式规则

allowedReferrers 的每一项都是指向一个允许调用的 origin 的字符串。请按下面的形式填写。

"allowedReferrers": [
  "https://shop.example.com",
  "https://*.shop.example.com",
  "http://localhost:3000"
]

列表中最多可以放 50 项，同一个 origin 不能放两次。每一项需要遵守的规则如下。

• scheme 只能使用 https。http 仅在 localhost、127.0.0.1、[::1] 上允许。
• 通配符只能以最前面的一个 *. 标签的形式使用。路径中不能使用通配符。
• 主机名请用 ASCII 填写。国际化域名请以 Punycode 形式填入。
• 端口的范围是 1 到 65535。省略时按 scheme 的默认端口（https 为 443，http 为 80）处理。
• 若填写了路径，则只有在与请求的路径完全一致时才能通过。浏览器会把路径做百分号编码后发送，因此路径中只能使用 ASCII。
• 带有用户信息（user@）、查询（?）或片段（#）的项会被拒绝。

该检查在创建、整体修改、部分修改这三条路径上都会执行。只要有一项不符合规则，整个列表就不会被保存，请求会被拒绝，并在错误原因中给出其中一个不符合规则的项（参见错误）。

Referer 判定

签发之后用该令牌调用 API 时，每个请求都会应用 allowedReferrers 来判定能否通过。

• 列表为空时不做限制。从任何 origin 调用都能通过。
• 列表中只要有一项，就会按请求的 Referer 头的值来判定。Origin 头不在判定范围内。
• 请求没有 Referer 头或该头的值为空时，请求会被拒绝。像服务器之间互相调用这样不发送 Referer 的地方要用的令牌，请把列表留空。
• 要通过判定，Referer 的 scheme、主机名、端口必须与列表中的某一项全部一致。若该项还带有路径，则路径也必须一致。
• https://*.shop.example.com 包含所有以 .shop.example.com 结尾的主机名（例如 admin.shop.example.com），但不包含 shop.example.com 本身。若要同时允许两者，请把 https://shop.example.com 也作为一项另行加入。
• 该判定作用于用该令牌发出的所有请求。无论调用 CMA 还是 CDA 的哪条路径都一样。
• 未通过判定的请求会以 HTTP 403 被拒绝。返回的错误码见下面的错误。

错误

以下是处理 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 签发数量限额。