Cloudflare API 403 怎麼查？用 documentation_url 找到缺少的權限

先看錯誤物件，不要只看 HTTP status#

官方範例的重點不是錯誤碼 10000，而是錯誤物件裡的 documentation_url：

1
{
2
  "success": false,
3
  "errors": [
4
    {
5
      "code": 10000,
6
      "message": "Forbidden",
7
      "documentation_url": "https://developers.cloudflare.com/api/resources/workers/subresources/beta/subresources/workers/methods/list"
8
    }
9
  ],
10
  "messages": [],
11
  "result": null
12
}

在本機或 CI 重新送出請求時，可以先把回應存成變數，再只印出錯誤欄位。不要把完整回應和 token 一起丟進公開 log：

1
response=$(curl -sS "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/workers/workers" -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN")
2

3
printf '%s\n' "$response" |
4
  jq -r '.errors[]? | [.code, .message, (.documentation_url // "(missing)")] | @tsv'

documentation_url 可能不存在，因此查詢要保留 fallback。Cloudflare 的公告用「nearly all product APIs」描述涵蓋範圍，客戶端不應把它當成永遠存在的欄位。

沿著文件網址讀三個區塊#

拿到網址後，先不要直接改 token。以 Cloudflare API 的 List Workers 文件為例，依序確認以下內容：

Cloudflare 的 API 文件會列出 endpoint 所需的權限。例如 List Workers 端點列出 Workers Scripts Read、Workers Scripts Write 與 Workers Tail Read 等可接受權限；這比看到 403 後猜一個「萬用」角色更可靠。

修正 token 前先核對 account 與權限範圍#

1
curl -sS "$API_URL" -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

用原始請求驗證，而不是只看 dashboard#

完成權限調整後，沿用原本的 method、URL 和必要 header 重試一次。建議把驗證流程固定成：

1. 保存 403 回應裡的 documentation_url 和 endpoint path。
2. 在官方文件中確認 Accepted Permissions、account／zone scope 與必要參數。
3. 由有權限的管理者調整最小範圍 token，或建立一組短期測試 token。
4. 用同一個 curl 或 API client 重試，確認成功後再把設定同步到 CI secret store。
5. 刪除不再使用的測試 token，並檢查 log 沒有留下 Authorization header。

如果你的 403 是 Workers AI 的付費模型或帳號資格問題，處理路徑和一般 API token permission 不同，可先看 Workers AI 403／5035 的模型與方案排查。

讓自動化讀文件，但不要自動放大權限#

documentation_url 很適合交給 CLI、CI 或 agent 做下一步文件定位，但它不應該直接觸發權限升級。自動化可以解析網址、抓取 endpoint 的 permission 說明、產生待審核差異；真正修改 token scope 仍應由人確認帳號、資源與用途。

實務上的完成條件是：原始請求已用最小可行 permission 通過，token 沒有被寫進輸出，且缺少 documentation_url 時仍能回到 API reference 和 permission list。這比「403 消失了」更能避免下一次部署又把高權限金鑰帶進錯的環境。

常見問題#