如何撤銷 Open Badge(以及接收者手中的副本會怎麼樣)

Open Badges 中的撤銷:它如何運作、接收者會看到什麼變化,以及如何正確處理「誤發」「憑證過期」和「違反政策」這幾種情況。

Nacho Coll 作者 更新於 18 分鐘閱讀
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 詳解會逐個欄位講解。

撤銷、重新簽發還是刪除:選對操作

在點擊任何按鈕之前,先判斷這三種操作中哪一種適合當前情況。它們不能互換。

情況最佳操作原因
憑證發給了錯的人,或存在拼寫錯誤刪除(如果從未寄出)或撤銷後重新簽發刪除會徹底移除紀錄;撤銷則保留稽核軌跡
學員違反了政策,或憑證是透過不正當方式取得的撤銷,並填寫原因紀錄仍可作為已撤銷狀態被驗證,這正是發生爭議時你需要的
憑證只是到了截止日期什麼都不用做;簽發時設定有效期限到期是正常的生命週期事件,不是撤銷
專案取消、整個梯次作廢批次撤銷一個任務、一個原因,套用於所有人
資訊有誤,但憑證本身仍然有效寄出前編輯,或寄出後撤銷並重新簽發讓接收者的體驗保持清爽

兩條經驗法則:

  1. 凡是真實的憑證,優先撤銷而不是刪除。 已刪除憑證的公開頁面會回傳「找不到」錯誤。已撤銷的憑證仍然可以解析,並清楚地標明已被撤銷,之後如果有人追問發生了什麼,這是好得多的證據。
  2. 永遠不要用撤銷來代替有效期限。 如果一張憑證只有兩年有效期,就在簽發時設定到期日期。悄悄過期的徽章與被收回的徽章是兩回事,你的驗證頁面應當說明是哪一種。

透過控制台撤銷

對於少量憑證,控制台是最快的方式,而且不需要寫程式。

  1. 登入後,在側邊欄中開啟 Awards。
  2. 找到該憑證。清單會顯示接收者、徽章名稱、簽發日期和有效期限,你也可以依接收者搜尋。
  3. 點擊該列(或 View)開啟憑證詳情視窗。
  4. 點擊 Revoke。
  5. 在確認對話框中,可以選填原因,也可以勾選 Email the recipient that their credential was revoked。
  6. 確認。

Award detail modal

該憑證會留在你的清單中,接收者旁邊有一個紅色的 Revoked 標記,這樣你和團隊隨時都能看到哪些被收回了。撤銷不會把這張憑證退還到你的方案額度中。你已經簽發了它,它就計入了用量。

關於原因欄位的說明

原因是選填的,但請填寫。它會隨憑證一起儲存,作為 revocationReason 出現在公開的 Open Badges 斷言中,並包含在你的系統收到的 webhook 負載裡。由於它在斷言上是公開的,請按寫給外部讀者的方式來寫。「誤發」或「專案已取消」都可以。「小李在第 14 題作弊」則不行。個人細節請保存在你自己的紀錄中,對外公開的原因保持中立。

要不要寄信給接收者?

通常要。一位學員如果直到雇主點擊驗證連結才發現自己的憑證已經失效,他們完全有理由對你不滿。通知之所以是選用的,正是因為有些撤銷(例如批次清理測試簽發的憑證)不需要打擾任何人。我們的建議:

  • **寄信的情況:**撤銷會影響到某個真實的人,而且對方可能仍在展示這張憑證。
  • **不寄信的情況:**你只是在清理內部測試資料,或作廢從未寄出的憑證。

一次撤銷多張憑證

專案很少只需要單獨撤銷一張憑證;更常見的是整個梯次。在 Awards 清單中:

  1. 勾選你想收回的憑證。
  2. 點擊批次操作列中的 Revoke selected。
  3. 填寫原因,決定是否通知接收者,然後確認。

批次撤銷作為持久的背景任務執行,所以幾百張憑證不會讓你的瀏覽器分頁逾時。已經撤銷的憑證會被略過,而不會導致整個批次失敗,中途中斷的任務也可以恢復。同樣的機制也支撐著從試算表批次簽發,我們在如何透過 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 設定中介紹過。

你今天就能採用的簡單撤銷政策

工具是容易的那一半。更難的是事先決定什麼時候撤銷、誰有權撤銷。一份簡短的書面政策可以避免日後的爭執。一個可行的範本:

  1. **撤銷的理由。**列出來:誤發、透過不當行為取得、不再滿足要求(例如會員資格失效)或專案被撤下。
  2. **誰來決定。**寫明一個角色,而不是某個人。把撤銷權限限定在該角色。
  3. **通知。**說明會透過電子郵件告知接收者並附上原因,除非該憑證從未送達。
  4. **申訴。**為接收者提供對決定提出異議的途徑,並說明你會在多長時間內回覆。如果申訴成功,請重新簽發一張新憑證,而不是試圖撤回撤銷,這樣歷史紀錄才會保持清晰。
  5. **紀錄。**保留一份內部備註,記錄誰撤銷了什麼以及為什麼,與中立的公開原因分開。

把這份政策發布在你介紹該憑證的同一個頁面上,讓獲得者在報名之前就了解規則。

需要避免的常見錯誤

  • **本想撤銷卻刪除了。**刪除是永久性的,無法復原,而且會讓公開頁面消失。僅在對無人見過的憑證出現真正的錯誤時使用。
  • **把私人細節寫進原因裡。**它在斷言上是公開的。
  • **指望已儲存的副本會改變。**撤銷存在於驗證端點。請告訴接收者從個人檔案和作品集中移除該憑證。
  • **用撤銷代替到期。**對有時限的憑證請使用到期日期。
  • **以為會退款。**已撤銷的憑證仍然計入你的方案額度。
  • **忘了下游系統。**接好 webhook,讓存取權限和紀錄跟隨憑證狀態變化。

常見問題

**我可以復原一次撤銷嗎?**無法透過介面操作。如果你誤撤銷了,請向接收者重新簽發一張新憑證。被撤銷的那張會作為稽核軌跡的一部分保留下來。

**接收者需要做什麼嗎?**不需要。如果你選擇通知他們,他們會收到一封郵件。否則,變化會在驗證頁面上悄悄發生。

**撤銷對從未寄出的憑證有效嗎?**有效,不過對於只有簡單錯誤的未寄出憑證,你可能更願意在寄出前編輯它,或者在無人見過的情況下刪除它。

**我能撤銷的數量有上限嗎?**批次撤銷作為可恢復的背景任務執行,所以大批量也能在一次操作中處理完,而不用一張一張地來。

**雇主會看到憑證已被撤銷嗎?**任何透過公開 URL 或斷言驗證該憑證的人,都會看到已撤銷的狀態,以及你填寫的原因(如果有)。

結語

撤銷一個 Open Badge 是一個很小的操作,卻對信任有著實實在在的影響。單張憑證就在控制台裡處理,整個梯次用批次撤銷,而當決定權在其他系統手中時,就用 API 或 webhook。保持原因中立,通知需要知情的人,並記住:撤銷改變的是驗證者看到的內容,而不是已經在接收者手中的檔案。

準備好簽發你的第一張可驗證憑證了嗎?在 badges.ninja 免費開始 — 視覺化設計器、公開驗證頁面、PDF 證書、Open Badge v2.0 輸出。無需信用卡。

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.

返回部落格

相關文章