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

返回博客

相关文章