如何撤销 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.


