如何撤銷 Open Badge(以及接收者手中的副本會怎麼樣)
Open Badges 中的撤銷:它如何運作、接收者會看到什麼變化,以及如何正確處理「誤發」「憑證過期」和「違反政策」這幾種情況。
任何簽發數位憑證的專案,遲早都得收回一張憑證。證書發給了錯的人。某位學員被發現在期末考核中作弊。與合作夥伴的合約到期了,寫著「Certified Partner」的徽章不該再有效。簽發是順利的那一面;撤銷才決定你的憑證是否真正值得信任。
本指南將說明 Open Badges 中的撤銷如何運作、撤銷之後接收者能看到什麼、看不到什麼,以及如何在 https://badges.ninja 上透過控制台或 API 撤銷單張憑證或幾百張憑證。
在 Open Badges 中,「撤銷」代表什麼
在 Open Badges v2.0 規範中,每個已簽發的徽章都是一個 assertion(斷言):一份託管在公開 URL 上的小型 JSON-LD 文件,內容是「這個簽發者在這一天把這個徽章授予了這位接收者」。撤銷,其實就是修改這份託管文件。斷言會加上 "revoked": true,還可以選擇加上 "revocationReason" 字串來說明原因。
這種設計帶來一個讓許多專案負責人意外的重要後果:
- 託管的斷言才是事實來源。 任何人透過取得斷言 URL 或開啟驗證頁面來驗證憑證,都會立刻看到已撤銷的狀態。
- 副本不會被召回。 如果接收者下載了徽章圖片或 JSON,或者把它固定到了作品集中,那個檔案不會改變。它仍然包含指向你託管斷言的連結,所以點擊連結的驗證者會看到它已被撤銷,但只是瞄一眼已儲存 PNG 的人看不到。
因此,撤銷是在驗證端點上發表的一項聲明,而不是刪除。可以把它想成在主紀錄上蓋一個「VOID」章,而不是去追回每一份影本。
如果想更仔細地看這份文件本身,我們的 Open Badge JSON-LD 詳解會逐個欄位講解。
撤銷、重新簽發還是刪除:選對操作
在點擊任何按鈕之前,先判斷這三種操作中哪一種適合當前情況。它們不能互換。
| 情況 | 最佳操作 | 原因 |
|---|---|---|
| 憑證發給了錯的人,或存在拼寫錯誤 | 刪除(如果從未寄出)或撤銷後重新簽發 | 刪除會徹底移除紀錄;撤銷則保留稽核軌跡 |
| 學員違反了政策,或憑證是透過不正當方式取得的 | 撤銷,並填寫原因 | 紀錄仍可作為已撤銷狀態被驗證,這正是發生爭議時你需要的 |
| 憑證只是到了截止日期 | 什麼都不用做;簽發時設定有效期限 | 到期是正常的生命週期事件,不是撤銷 |
| 專案取消、整個梯次作廢 | 批次撤銷 | 一個任務、一個原因,套用於所有人 |
| 資訊有誤,但憑證本身仍然有效 | 寄出前編輯,或寄出後撤銷並重新簽發 | 讓接收者的體驗保持清爽 |
兩條經驗法則:
- 凡是真實的憑證,優先撤銷而不是刪除。 已刪除憑證的公開頁面會回傳「找不到」錯誤。已撤銷的憑證仍然可以解析,並清楚地標明已被撤銷,之後如果有人追問發生了什麼,這是好得多的證據。
- 永遠不要用撤銷來代替有效期限。 如果一張憑證只有兩年有效期,就在簽發時設定到期日期。悄悄過期的徽章與被收回的徽章是兩回事,你的驗證頁面應當說明是哪一種。
透過控制台撤銷
對於少量憑證,控制台是最快的方式,而且不需要寫程式。
- 登入後,在側邊欄中開啟 Awards。
- 找到該憑證。清單會顯示接收者、徽章名稱、簽發日期和有效期限,你也可以依接收者搜尋。
- 點擊該列(或 View)開啟憑證詳情視窗。
- 點擊 Revoke。
- 在確認對話框中,可以選填原因,也可以勾選 Email the recipient that their credential was revoked。
- 確認。

該憑證會留在你的清單中,接收者旁邊有一個紅色的 Revoked 標記,這樣你和團隊隨時都能看到哪些被收回了。撤銷不會把這張憑證退還到你的方案額度中。你已經簽發了它,它就計入了用量。
關於原因欄位的說明
原因是選填的,但請填寫。它會隨憑證一起儲存,作為 revocationReason 出現在公開的 Open Badges 斷言中,並包含在你的系統收到的 webhook 負載裡。由於它在斷言上是公開的,請按寫給外部讀者的方式來寫。「誤發」或「專案已取消」都可以。「小李在第 14 題作弊」則不行。個人細節請保存在你自己的紀錄中,對外公開的原因保持中立。
要不要寄信給接收者?
通常要。一位學員如果直到雇主點擊驗證連結才發現自己的憑證已經失效,他們完全有理由對你不滿。通知之所以是選用的,正是因為有些撤銷(例如批次清理測試簽發的憑證)不需要打擾任何人。我們的建議:
- **寄信的情況:**撤銷會影響到某個真實的人,而且對方可能仍在展示這張憑證。
- **不寄信的情況:**你只是在清理內部測試資料,或作廢從未寄出的憑證。
一次撤銷多張憑證
專案很少只需要單獨撤銷一張憑證;更常見的是整個梯次。在 Awards 清單中:
- 勾選你想收回的憑證。
- 點擊批次操作列中的 Revoke selected。
- 填寫原因,決定是否通知接收者,然後確認。
批次撤銷作為持久的背景任務執行,所以幾百張憑證不會讓你的瀏覽器分頁逾時。已經撤銷的憑證會被略過,而不會導致整個批次失敗,中途中斷的任務也可以恢復。同樣的機制也支撐著從試算表批次簽發,我們在如何透過 CSV 簽發 Open Badges中介紹過。
透過 API 撤銷
如果由你的學習系統或人資平台來決定誰不再具備認證資格,你可以透過程式撤銷。端點是 POST /awards/{awardId}/revoke,使用 API 金鑰(X-Api-Key: bws_<32-hex>)或 Cognito Bearer 權杖進行驗證。award ID 放在路徑中;reason 和 notify 放在 JSON 請求本文中,兩者都是選填的。
使用 curl:
curl -X POST https://api.badges.ninja/awards/<award-id>/revoke \
-H "X-Api-Key: bws_YOUR_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{"reason":"Issued to the wrong recipient","notify":true}'
# 200 -> {"revoked":true,"awardId":"<award-id>"}
使用 JavaScript:
const res = await fetch(`https://api.badges.ninja/awards/${awardId}/revoke`, {
method: "POST",
headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ reason: "Program cancelled", notify: false }),
});
const { revoked } = await res.json(); // true
使用 Python:
import requests
res = requests.post(
f"https://api.badges.ninja/awards/{award_id}/revoke",
headers={"X-Api-Key": API_KEY},
json={"reason": "Program cancelled", "notify": False},
)
print(res.json()["revoked"]) # True
一些值得了解的實用細節:
- **它是冪等的。**對已經撤銷的憑證再次撤銷,會回傳同樣的成功回應,並且不會寄出第二次通知。因此可以放心地在帶重試的任務中呼叫。
- 原因會被截斷為 500 個字元。
- **
notify預設為 false。**除非你要求,否則不會寄出任何郵件。 - 批次撤銷可透過批次端點完成,使用
action: "revoke"和一組 award ID;它會回傳一個可供你追蹤的任務 ID。完整參數見 awards API 參考。
只有當撤銷由其他系統驅動時,你才需要用到 API。對於一次性的操作,控制台更快,而且有確認步驟,能避免你輸錯 ID。
接收者和驗證者會看到什麼
撤銷之後,以下是會發生的變化,以及生效的速度。
**在公開驗證頁面上。**位於 https://badges.ninja/awards/<award-id> 的頁面會把憑證顯示為已撤銷,用於社群分享的頁面標題會加上「[Revoked]」前綴,這樣分享出去的連結在預覽卡片中就不會看起來像一張有效憑證。
**在 Open Badges v2.0 斷言中。**位於 https://api.badges.ninja/certify-badge/award/<award-id> 的託管 JSON 現在帶有 "revoked": true,如果你填寫了原因,還會帶有 "revocationReason"。已撤銷的斷言只快取約 30 秒,而有效的斷言快取五分鐘,因此變更會很快傳達到驗證者。
**在 Open Badges 3.0 憑證中。**撤銷還會翻轉該憑證在 W3C Bitstring Status List 中的位元,可驗證憑證錢包和驗證者正是藉此偵測撤銷狀態。該清單的快取時間很短,預計一分鐘左右即可傳播完畢。如果你正在權衡這兩個版本,請參閱 Open Badges v2 vs v3。
**在接收者自己的副本中。**他們下載的檔案不會有任何變化。他們筆記型電腦上的徽章圖片看起來一模一樣。變化的是驗證的結果:任何點擊連結或透過程式檢查該憑證的人,得到的都是已撤銷的答案。如果你通知了他們,他們還會收到一封說明原因的郵件。
**在 LinkedIn 上。**加入 LinkedIn 個人檔案的憑證,是一個連結加上指向你驗證頁面的中繼資料。LinkedIn 不會替你輪詢撤銷狀態,所以該項目可能仍留在個人檔案上,但任何點擊連結的人都會進入已撤銷頁面。這也是要寄出通知並請接收者刪除該項目的另一個原因。
通知你自己的系統:webhook
撤銷在你的組織內部很少就此結束。學員可能需要失去某個社群的存取權,雇主紀錄可能需要更新,CRM 標籤可能需要移除。當一張憑證被撤銷時,Badges Ninja 會發出 credential.revoked webhook 事件,附帶 award URL 和原因:
{
"awardId": "https://api.badges.ninja/certify-badge/award/<award-id>",
"reason": "Issued in error"
}
訂閱它,你的下游系統就能保持同步,而不需要有人記得去更新。設定細節見 webhook 文件,更完整的事件模型我們在徽章事件的 webhook 設定中介紹過。
你今天就能採用的簡單撤銷政策
工具是容易的那一半。更難的是事先決定什麼時候撤銷、誰有權撤銷。一份簡短的書面政策可以避免日後的爭執。一個可行的範本:
- **撤銷的理由。**列出來:誤發、透過不當行為取得、不再滿足要求(例如會員資格失效)或專案被撤下。
- **誰來決定。**寫明一個角色,而不是某個人。把撤銷權限限定在該角色。
- **通知。**說明會透過電子郵件告知接收者並附上原因,除非該憑證從未送達。
- **申訴。**為接收者提供對決定提出異議的途徑,並說明你會在多長時間內回覆。如果申訴成功,請重新簽發一張新憑證,而不是試圖撤回撤銷,這樣歷史紀錄才會保持清晰。
- **紀錄。**保留一份內部備註,記錄誰撤銷了什麼以及為什麼,與中立的公開原因分開。
把這份政策發布在你介紹該憑證的同一個頁面上,讓獲得者在報名之前就了解規則。
需要避免的常見錯誤
- **本想撤銷卻刪除了。**刪除是永久性的,無法復原,而且會讓公開頁面消失。僅在對無人見過的憑證出現真正的錯誤時使用。
- **把私人細節寫進原因裡。**它在斷言上是公開的。
- **指望已儲存的副本會改變。**撤銷存在於驗證端點。請告訴接收者從個人檔案和作品集中移除該憑證。
- **用撤銷代替到期。**對有時限的憑證請使用到期日期。
- **以為會退款。**已撤銷的憑證仍然計入你的方案額度。
- **忘了下游系統。**接好 webhook,讓存取權限和紀錄跟隨憑證狀態變化。
常見問題
**我可以復原一次撤銷嗎?**無法透過介面操作。如果你誤撤銷了,請向接收者重新簽發一張新憑證。被撤銷的那張會作為稽核軌跡的一部分保留下來。
**接收者需要做什麼嗎?**不需要。如果你選擇通知他們,他們會收到一封郵件。否則,變化會在驗證頁面上悄悄發生。
**撤銷對從未寄出的憑證有效嗎?**有效,不過對於只有簡單錯誤的未寄出憑證,你可能更願意在寄出前編輯它,或者在無人見過的情況下刪除它。
**我能撤銷的數量有上限嗎?**批次撤銷作為可恢復的背景任務執行,所以大批量也能在一次操作中處理完,而不用一張一張地來。
**雇主會看到憑證已被撤銷嗎?**任何透過公開 URL 或斷言驗證該憑證的人,都會看到已撤銷的狀態,以及你填寫的原因(如果有)。
結語
撤銷一個 Open Badge 是一個很小的操作,卻對信任有著實實在在的影響。單張憑證就在控制台裡處理,整個梯次用批次撤銷,而當決定權在其他系統手中時,就用 API 或 webhook。保持原因中立,通知需要知情的人,並記住:撤銷改變的是驗證者看到的內容,而不是已經在接收者手中的檔案。
準備好簽發你的第一張可驗證憑證了嗎?在 badges.ninja 免費開始 — 視覺化設計器、公開驗證頁面、PDF 證書、Open Badge v2.0 輸出。無需信用卡。
本文章是如何完成的
本部落格的部分文章是在 AI 助理協助下起草,並在發布前由 Badges Ninja 團隊審閱、查證與編輯。所有程式碼範例與價格皆已對照正式產品驗證。如需了解我們的編輯與 AI 流程,請參閱我們的 編輯流程頁面 .

關於作者
Nacho Coll
Founder & Engineer at Badges Ninja
Nacho founded Badges Ninja to make issuing verifiable digital credentials as simple as a single API call — Open Badge v2.0 badges and certificates, minted, hosted, and verifiable without standing up your own issuer infrastructure. Writes about the Open Badges spec, credential verification, and running a credentialing platform serverless on AWS, from the operator side of the wire.


