跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

API 令牌模板 URL

最后更新 查看 MarkdownAgent 设置

使用模板 URL 生成具有预配置权限的 Cloudflare API 令牌。模板 URL 允许您与用户共享令牌要求,而无需在仪表板中手动选择权限。

模板 URL 使用查询参数预填 Cloudflare 仪表板中的 API 令牌创建页面。当用户打开模板 URL 时,仪表板会自动配置指定的权限和设置。

Cloudflare 同时支持用户 API 令牌和账户 API 令牌的模板 URL。有关这两种令牌类型之间差异的更多信息,请参阅 账户 API 令牌。

用户令牌 URL 格式

用户令牌模板 URL 会在用户配置文件级别(/profile/api-tokens)打开令牌创建表单。以此方式创建的令牌归用户所有。

基本模板 URL 结构为:

https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=[ENCODED_PERMISSIONS]&accountId=*&zoneId=all&name=[TOKEN_NAME]

URL 组件

参数 必填 描述
permissionGroupKeys 是 URL 编码的 JSON 权限对象数组
accountId 是 账户作用域(使用 * 表示所有账户)
zoneId 是 Zone 作用域(使用 all 表示所有 zone)
name 否 预填的令牌名称

账户令牌 URL 格式

账户令牌模板 URL 会在账户级别打开令牌创建表单。以这种方式创建的令牌归账户所有(服务主体令牌),不与任何个人用户绑定。有关角色和权限要求,请参阅账户 API 令牌。

基本模板 URL 结构为:

https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=[ENCODED_PERMISSIONS]&name=[TOKEN_NAME]

:account 段是占位符。当用户打开 URL 时,如果其有权访问多个账户,仪表板会提示其选择账户。

URL 组件

参数 必填 描述
permissionGroupKeys 是 URL 编码的 JSON 权限对象数组
name 否 预填的令牌名称

权限格式

用户令牌模板 URL 和账户令牌模板 URL 使用相同的权限编码:一个具有以下结构的 JSON 数组。

[{ "key": "permission_name", "type": "read|edit|revoke|run|purge" }]

这两种令牌类型对这些条目的解析方式不同,详见以下各节。

对于账户令牌 URL,每个 key 可以是简短权限键(例如 dns),也可以是权限组 ID。使用权限组 ID 最可靠,因为它会精确对应一个组。请参阅使用权限组 ID。

对于用户令牌 URL,每个 key 必须是与某个组的 name 完全匹配的简短权限键,并且 type 必须是 edit(而非 write)、read、revoke、run 或 purge。不支持权限组 ID;任何不匹配的条目都会被静默丢弃。

权限类型

类型 描述
read 只读访问
edit 完全访问(创建、读取、更新、删除)
revoke 撤销权限
run 执行权限
purge 清除权限

使用权限组 ID

若要在账户令牌 URL 中指定任何权限组(包括权限参考中没有简短键的组),请将其权限组 ID 用作 key:

[{ "key": "82e64a83756745bbbb1c9c2701bf816b", "type": "edit" }]

权限组 ID 是权限组稳定的规范标识符。它们与 Create token端点和 Cloudflare Terraform 提供程序接受的 ID 相同,因此模板 URL 可通过 ID 预选任意权限组。由于 ID 指定唯一的组,传入 ID 时会忽略 type 字段。

同一数组中可以组合多个 ID,与使用简短键的方式相同:

[
    { "key": "e086da7e2179491d91ee5f35b3ca210a", "type": "edit" },
    { "key": "7cf72faf220841aabcfdfab81c43c4f6", "type": "read" }
]

由于账户令牌 URL 会创建账户所有的令牌,请通过账户作用域的列出权限组端点查询其权限组 ID。请求所用令牌需要具有 API Tokens Read 账户权限:

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/tokens/permission_groups" \
    --header "Authorization: Bearer <API_TOKEN>"

对于用户令牌,请改用用户作用域端点,它会返回用户令牌可用的权限组:

curl "https://api.cloudflare.com/client/v4/user/tokens/permission_groups" \
    --header "Authorization: Bearer <API_TOKEN>"

每个结果都包含权限组 id 和 name。API 令牌权限参考也列出了这些 ID。

创建自定义模板

1. 确定所需权限

列出您的使用场景所需的权限。请参阅权限参考表。

2. 创建权限 JSON

将权限格式化为 JSON 数组:

[
    { "key": "dns", "type": "edit" },
    { "key": "analytics", "type": "read" }
]

3. URL 编码 JSON

使用 URL 编码器转换 JSON 字符串:

%5B%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22analytics%22%2C%22type%22%3A%22read%22%7D%5D

4. 构建完整 URL

对于用户令牌,将所有组件组合成最终模板 URL:

https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=[ENCODED_JSON]&accountId=*&zoneId=all&name=Custom%20Token

对于账户令牌,请改用账户级别路径:

https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=[ENCODED_JSON]&name=Custom%20Token

权限参考

使用此表查找自定义模板所需的权限键。

账户权限

权限键 描述 常见使用场景
account_analytics 账户分析 报告、监控
account_api_tokens API 令牌管理 令牌自动化
account_settings 账户配置 账户管理
billing 账单信息 成本跟踪、开票
workers_scripts Workers 脚本 无服务器函数
workers_kv_storage Workers KV 存储 数据存储
workers_routes Workers 路由 流量路由
workers_r2 R2 存储 对象存储
d1 D1 数据库 SQL 数据库
queues Queues 消息队列
page Cloudflare Pages Pages 部署
stream Stream 视频流
images Images 图像优化
account_logs 日志 日志管理

Zone 权限

权限键 描述 常见使用场景
dns DNS 记录 域名管理
zone Zone 管理 域名配置
zone_settings Zone 设置 Zone 配置
analytics Zone 分析 性能监控
firewall_services 防火墙规则 安全管理
page_rules 页面规则 流量控制
cache 缓存清除 内容更新
ssl_and_certificates SSL/TLS 证书 证书管理
logs 日志 日志管理

Access 权限

权限键 描述 常见使用场景
access Access 应用程序 Zero Trust 应用
access_acct Access 组织 身份管理
access_audit_log Access 审计日志 合规、安全
access_custom_page 自定义页面 品牌、用户体验
teams Zero Trust Gateway、CASB、DLP

常见权限模板

以下模板 URL 可用于常见场景。每个示例都提供用户令牌 URL 和账户令牌 URL。

DNS 管理

创建用于 DNS 记录管理的令牌。

用户令牌

使用场景 模板 URL
DNS 只读 https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22read%22%7D%5D&accountId=%2A&zoneId=all&name=DNS%20Read%20Token
DNS 读写 https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22edit%22%7D%5D&accountId=%2A&zoneId=all&name=DNS%20Management%20Token

账户令牌

使用场景 模板 URL
DNS 只读 https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22read%22%7D%5D&name=DNS%20Read%20Token
DNS 读写 https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22edit%22%7D%5D&name=DNS%20Management%20Token

Workers 开发

创建用于 Workers、KV 存储及相关服务的令牌。

用户令牌

使用场景 模板 URL
仅 Workers 脚本 https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22workers_scripts%22%2C%22type%22%3A%22edit%22%7D%5D&accountId=%2A&zoneId=all&name=Workers%20Scripts%20Token
Workers 完全访问 https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22workers_scripts%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22workers_kv_storage%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22workers_routes%22%2C%22type%22%3A%22edit%22%7D%5D&accountId=%2A&zoneId=all&name=Workers%20Full%20Access%20Token

账户令牌

使用场景 模板 URL
仅 Workers 脚本 https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22workers_scripts%22%2C%22type%22%3A%22edit%22%7D%5D&name=Workers%20Scripts%20Token
Workers 完全访问 https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22workers_scripts%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22workers_kv_storage%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22workers_routes%22%2C%22type%22%3A%22edit%22%7D%5D&name=Workers%20Full%20Access%20Token

分析与监控

创建用于访问分析和日志的令牌。

用户令牌

使用场景 模板 URL
账户分析 https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22account_analytics%22%2C%22type%22%3A%22read%22%7D%5D&accountId=%2A&zoneId=all&name=Account%20Analytics%20Token
Zone 分析 https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22analytics%22%2C%22type%22%3A%22read%22%7D%5D&accountId=%2A&zoneId=all&name=Zone%20Analytics%20Token

账户令牌

使用场景 模板 URL
账户分析 https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22account_analytics%22%2C%22type%22%3A%22read%22%7D%5D&name=Account%20Analytics%20Token
Zone 分析 https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22analytics%22%2C%22type%22%3A%22read%22%7D%5D&name=Zone%20Analytics%20Token

Zero Trust 管理

创建用于 Cloudflare Zero Trust 管理的令牌。

用户令牌

使用场景 模板 URL
Access 应用程序只读 https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22access%22%2C%22type%22%3A%22read%22%7D%5D&accountId=%2A&zoneId=all&name=Access%20Read%20Token
Access 完全管理 https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22access%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22access_acct%22%2C%22type%22%3A%22edit%22%7D%5D&accountId=%2A&zoneId=all&name=Access%20Management%20Token

账户令牌

使用场景 模板 URL
Access 应用程序只读 https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22access%22%2C%22type%22%3A%22read%22%7D%5D&name=Access%20Read%20Token
Access 完全管理 https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22access%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22access_acct%22%2C%22type%22%3A%22edit%22%7D%5D&name=Access%20Management%20Token

最佳实践

创建和共享模板 URL 时,请遵循以下准则。

  • 最小权限原则:仅请求使用场景所需的最小权限。这可以在令牌泄露时降低安全风险。
  • 使用描述性令牌名称:在模板 URL 中包含清晰、描述性的名称,帮助用户理解令牌的用途。
  • 记录令牌用法:提供清晰的文档,说明每个令牌的用途以及不再需要时如何撤销。
  • 定期轮换令牌:鼓励用户定期轮换令牌并审查权限。
  • 共享前先测试:在与用户共享之前,始终在预发布环境中测试模板 URL。

故障排除

查看常见问题及解决方案列表。

问题 解决方案
URL 未预填权限 验证 JSON 是否已正确 URL 编码
权限缺失 请对照参考表检查权限键,或使用其权限组 ID指定权限组。
令牌名称未显示 确保 name 参数已 URL 编码
访问被拒绝错误 验证用户在账户中是否具有所需权限

对于账户令牌 URL,如果模板 URL 中包含无法解析的键,或 permissionGroupKeys 值不是有效 JSON,控制面板仍会打开令牌创建表单,并填入可解析的内容,同时显示无法应用的键。它不会返回令牌列表,因此拼写错误的键会在表单中显现,而不是被静默忽略。

对于用户令牌 URL,无法解析的条目会被静默丢弃,也不会显示提示。因此,分享 URL 前请对照权限参考核对每个键。

此外,在共享模板 URL 之前,请查看以下清单。

  • 所有权限键均正确
  • JSON 语法有效
  • URL 编码正确
  • 令牌名称具有描述性
  • 权限遵循最小权限原则

相关资源

这篇文档对您有帮助吗?