API key

呼叫 CBETA API 時，請在 HTTP header 帶上您的 API key：

Authorization: Bearer <api_key>

登入取得 API key （用 Google 或 GitHub 帳號登入即可）。

目前是過渡期

沒帶 key 仍然可以呼叫 API，既有程式不會壞掉。
過渡期結束後，沒帶 key 就會收到 401。 結束日期會另行公告，請及早改成帶 key。
過渡期內若您的回應帶有 X-CBETA-API-Key: recommended 這個 header，表示這次呼叫沒有帶 key，過渡期結束後就會失敗。這是最可靠的自我檢查方式。
⚠️ 但如果您帶了 key，就一定會被驗證。 key 無效或已撤銷時現在就會收到 401，不會靜默放行 —— 這樣才不會讓您誤以為 key 設定正確，等過渡期結束才一次爆掉。

誰需要 API key？

呼叫方式	需要 key？	說明
研究者的程式或腳本（Python、R、Ruby…）	✅ 需要	請登入取得
第三方 app、server-to-server 呼叫	✅ 需要	請登入取得
網頁前端（瀏覽器裡的 JavaScript）	❌ 不支援	key 寫在前端 JS 裡等於公開，無法保護，因此瀏覽器前端不能直接呼叫本 API，我們也不接受網站來源（Origin）登記申請。過渡期結束後，這類呼叫會收到 `401`。請改由您自己的後端帶 key 呼叫，前端再向您的後端取資料。

使用方式

curl

curl -H "Authorization: Bearer $CBETA_API_KEY" \
  "https://cbdata.dila.edu.tw/stable/search?q=%E7%84%A1%E5%B8%B8"

Python

import os, requests

r = requests.get(
    "https://cbdata.dila.edu.tw/stable/search",
    params={"q": "無常"},
    headers={"Authorization": f"Bearer {os.environ['CBETA_API_KEY']}"},
)
r.raise_for_status()

Ruby

require 'faraday'

res = Faraday.get('https://cbdata.dila.edu.tw/stable/search',
                  { q: '無常' },
                  { 'Authorization' => "Bearer #{ENV.fetch('CBETA_API_KEY')}" })

只能放在 header

不接受用 query string 傳 key（例如 ?api_key=…）。 query string 會被寫進伺服器的 access log、Rails log 與存取統計，等於在多個地方留下 key 的明文。

額度

	額度
沒帶 key	每分鐘 60 次（依 IP 計算）
帶有效的 key	每分鐘 300 次（依帳號計算）

額度是硬上限，超過會收到 429，並帶 Retry-After header 告知要等幾秒。請依照它退讓重試，不要持續重打。下面的建議值則是為了保留安全餘裕。

建議的呼叫頻率

除了上面的額度之外，伺服器還有一道依 IP 計算的防護： 短時間內集中送出大量 request，整個 IP 會被封鎖一段時間，期間所有呼叫都會失敗，而且不會收到 429 提醒。為了安全，建議把流量控制在以下範圍：

沒帶 key：每分鐘不超過 30 次
帶有效的 key：每分鐘不超過 150 次
平均分散送出，不要在短時間內集中送出：任何一秒都不要超過 4 次，也不要同時平行送出多個 request

要注意的是：

被回 429 的 request 仍然算在流量裡，收到後若繼續重打，最後還是會被封鎖。
這道防護是依 IP 計算，同一個對外 IP 後面的多台電腦（例如同一個機構的網路）流量會合併計算。

管理您的 key

到我的帳號可以：

查看目前有效的 key（顯示前綴、建立時間、最後使用時間）。
產生新的 key。明文只在產生的當下顯示一次，請立刻複製保存。
撤銷 key（立即生效）。
查看自己每日的呼叫次數。

懷疑 key 外流時

到帳號頁看「最後使用」時間。若那不是您使用的時間，key 很可能已外流。
立刻撤銷該把 key —— 撤銷是立即生效的，不會有快取延遲。
產生新的 key，更新您的程式。

每個帳號同時最多可以有 2 把有效的 key。保留兩把是為了讓您能無縫更換：先產生新的 → 把用到舊 key 的程式都改過來 → 再撤銷舊的，中間不會斷線。

安全性

本站不儲存 key 的明文，只存單向雜湊值（SHA-256）。忘記了只能重新產生。
key 的格式是 cbeta_ 加上 32 bytes 的隨機值。
請把 key 當成密碼：放環境變數，不要 commit 進版控、不要寫在前端 JS 裡。
撤銷是軟刪除，我們會保留撤銷紀錄以供稽核，但該 key 立即失效。

錯誤回應

HTTP status	意思	怎麼處理
%code 401	key 無效、已撤銷，或（過渡期結束後）沒帶 key	檢查 header 拼寫，或到帳號頁確認 key 還有效
%code 429	超過額度	依 `Retry-After` 等待後重試