使用模板 URL 生成具有预配置权限的 Cloudflare API 令牌。模板 URL 允许您与用户共享令牌要求,而无需在仪表板中手动选择权限。
模板 URL 使用查询参数预填 Cloudflare 仪表板中的 API 令牌创建页面。当用户打开模板 URL 时,仪表板会自动配置指定的权限和设置。
Cloudflare 同时支持用户 API 令牌和账户 API 令牌的模板 URL。有关这两种令牌类型之间差异的更多信息,请参阅 账户 API 令牌。
用户令牌模板 URL 会在用户配置文件级别(/profile/api-tokens)打开令牌创建表单。以此方式创建的令牌归用户所有。
基本模板 URL 结构为:
https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=[ENCODED_PERMISSIONS]&accountId=*&zoneId=all&name=[TOKEN_NAME]| 参数 | 必填 | 描述 |
|---|---|---|
permissionGroupKeys |
是 | URL 编码的 JSON 权限对象数组 |
accountId |
是 | 账户作用域(使用 * 表示所有账户) |
zoneId |
是 | Zone 作用域(使用 all 表示所有 zone) |
name |
否 | 预填的令牌名称 |
账户令牌模板 URL 会在账户级别打开令牌创建表单。以这种方式创建的令牌归账户所有(服务主体令牌),不与任何个人用户绑定。有关角色和权限要求,请参阅账户 API 令牌。
基本模板 URL 结构为:
https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=[ENCODED_PERMISSIONS]&name=[TOKEN_NAME]:account 段是占位符。当用户打开 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 |
清除权限 |
若要在账户令牌 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。
列出您的使用场景所需的权限。请参阅权限参考表。
将权限格式化为 JSON 数组:
[
{ "key": "dns", "type": "edit" },
{ "key": "analytics", "type": "read" }
]使用 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对于用户令牌,将所有组件组合成最终模板 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 |
日志 | 日志管理 |
| 权限键 | 描述 | 常见使用场景 |
|---|---|---|
dns |
DNS 记录 | 域名管理 |
zone |
Zone 管理 | 域名配置 |
zone_settings |
Zone 设置 | Zone 配置 |
analytics |
Zone 分析 | 性能监控 |
firewall_services |
防火墙规则 | 安全管理 |
page_rules |
页面规则 | 流量控制 |
cache |
缓存清除 | 内容更新 |
ssl_and_certificates |
SSL/TLS 证书 | 证书管理 |
logs |
日志 | 日志管理 |
| 权限键 | 描述 | 常见使用场景 |
|---|---|---|
access |
Access 应用程序 | Zero Trust 应用 |
access_acct |
Access 组织 | 身份管理 |
access_audit_log |
Access 审计日志 | 合规、安全 |
access_custom_page |
自定义页面 | 品牌、用户体验 |
teams |
Zero Trust | Gateway、CASB、DLP |
以下模板 URL 可用于常见场景。每个示例都提供用户令牌 URL 和账户令牌 URL。
创建用于 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、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 |
创建用于 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 编码正确
- 令牌名称具有描述性
- 权限遵循最小权限原则