Delivery Access Token

DeliveryAccessToken 是从 CDA（公开传递）读取已发布内容时使用的只读令牌。网站或应用的浏览器在获取已发布内容时，使用该令牌调用 CDA。签发时会将其绑定到一个 SpaceRole，由该角色决定令牌的读取范围（可以读取哪些 Content Type）。

在 CMA 中，DeliveryAccessToken 是 Space 的下级资源，路径以 /spaces/{spaceId}/delivery-access-tokens 为基准。该令牌在向浏览器（客户端）暴露的状态下运行，因此所绑定的角色必须设为仅读取所需 Content Type 的最小权限（least-privilege）（参见下文 安全：最小权限绑定）。除此之外，只要在 allowedReferrers 中放入允许调用的 origin，该令牌在指定的站点之外就无法使用（参见 origin 格式规则和 Referer 判定）。

资源结构

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

{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7PUFQuOAqWOc",
    "type": "DeliveryAccessToken",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "user": { "sys": { "id": "3trmXRLdJIqc9GPBbyFYQQw6hf9kGj", "type": "Refer", "targetType": "User" } },
    "createdBy": { "sys": { "id": "3trmXRM3RqbgSnifyg7PUFQsSPi0nt", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T09:24:23.156Z",
    "updatedBy": { "sys": { "id": "3trmXRM3RqbgSnifyg7PUFQsSPi0nt", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T09:24:23.156Z",
    "accessToken": "DVRATbQ8mX2vK9pLs7Rf1Zt0Nc4Wd6Hg5Ua2Ee9Ck3PoYx8Bj6Hg5Ua2Ee9Ck3Po…",
    "scopes": ["DELIVERY_ACCESS_TOKEN"]
  },
  "allowedReferrers": ["https://shop.example.com"],
  "description": "服装商城公开站点专用的只读交付令牌",
  "name": "网站公开交付"
}

主要键：

• sys.id：DeliveryAccessToken 的唯一标识符。用于单条查询、修改、删除路径中的 {deliveryAccessTokenId}。
• sys.accessToken：调用 CDA 时使用的密钥令牌值。签发后再次查询也会原样返回同一个值，因此需注意避免暴露（参见下文安全章节）。
• sys.scopes：令牌的权限范围。DeliveryAccessToken 在签发时始终为 ["DELIVERY_ACCESS_TOKEN"]。
• sys.user：该令牌的权限主体，即其专用用户。在签发时自动创建，所绑定的 SpaceRole 的权限会授予该用户。也就是说，令牌的实际权限来自该用户。它与实际签发该令牌的人（sys.createdBy）是不同的用户。
• name：创建时指定的令牌名称（例如 网站公开交付）。
• description：对令牌的说明（可选）。
• allowedReferrers：限制该令牌可以从哪些 origin 调用的列表。列表为空时不做限制。上面的示例是只有从服装商城的公开站点（https://shop.example.com）调用时才能通过的令牌（格式规则和判定方式参见 origin 格式规则和 Referer 判定）。

上例中的 accessToken 是密钥值，因此已替换为示例字符串。实际为一段较长的不透明字符串，签发后再次查询会返回同一个值。

系统属性 (sys)

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

正文属性：

安全：最小权限绑定

DeliveryAccessToken 是在向浏览器和访问者暴露的状态下调用 CDA 的令牌。因此，将其绑定到哪个 SpaceRole 就成了该令牌的安全边界。

• 在创建请求的 role 中填入 仅读取所需 Content Type 的最小权限 SpaceRole 的 sys.id。公开传递推荐使用只读角色。
• 绝不绑定 Administrator 角色。 该令牌会暴露给客户端，若绑定带有管理权限的角色，那些权限就会原样泄露到外部。此外，不要随手使用 SpaceRole 列表中的第一项，而应明确指定预期的最小权限角色的 sys.id。
• 请用 allowedReferrers 把可以使用该令牌的位置也一并限定。 所绑定的角色决定用该令牌能读取什么，这个列表则决定可以从哪里调用。在浏览器中运行的令牌无法隐藏令牌值本身，因此只要把公开站点的 origin 放进列表，即使令牌值泄露到外部，从该站点之外发起的 CDA 调用也无法通过（参见 Referer 判定）。
• accessToken 是签发后也会以同一个值被查询到的密钥值。请将其安全地注入客户端构建，不要原样暴露到外部。

状态与约束

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

关于绑定与权限的规则：

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

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 判定

签发之后用该令牌调用 CDA 时，每个请求都会应用 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 也作为一项另行加入。
• 该判定作用于用该令牌发出的所有请求。无论调用 CDA 的哪条路径都一样。
• 未通过判定的请求会以 HTTP 403 被拒绝。返回的错误码见下面的错误。

错误

以下是处理 DeliveryAccessToken 时会遇到的错误码。所有资源共通的错误码，请参见通用错误。

API

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

相关文档

• SpaceRole：定义要绑定到该令牌的角色（读取范围）。
• CDA 概览：用该令牌读取已发布内容的传递 API。
• Space Access Token：在一个 Space 内连写入都能做的令牌（具有同样的 origin 限制）。
• Personal Access Token：用于服务器与 CI 的 Weegloo User 令牌。