Com revocar una insígnia Open Badge (i què passa amb la còpia del destinatari)

La revocació a Open Badges: com funciona, què canvia per al destinatari i la manera correcta de gestionar «emesa per error», «credencial caducada» i «incompliment de la política».

Nacho Coll Per Actualitzat 12 min de lectura
La revocació a Open Badges: com funciona, què canvia per al destinatari i la manera correcta de gestionar «emesa per error», «credencial caducada» i «incompliment de la política».

Tard o d’hora, tots els programes que emeten credencials digitals n’han de retirar alguna. Un certificat va anar a parar a la persona equivocada. Es va descobrir que un alumne havia fet trampes a l’avaluació final. Un contracte amb un soci va acabar i les insígnies que deien «Soci certificat» ja no haurien de ser vàlides. Emetre és el camí fàcil; la revocació és la part que decideix si es pot confiar de debò en les teves credencials.

Aquesta guia explica com funciona la revocació a Open Badges, què veu (i què no) el destinatari després, i com revocar una credencial o unes quantes centenars a https://badges.ninja, des del tauler o amb l’API.

Què vol dir «revocar» a Open Badges

A l’especificació Open Badges v2.0, cada insígnia emesa és una asserció: un petit document JSON-LD allotjat en una URL pública que diu «aquest emissor va concedir aquesta insígnia a aquest destinatari en aquesta data». La revocació és simplement un canvi en aquest document allotjat. L’asserció passa a tenir "revoked": true i, opcionalment, una cadena "revocationReason" que explica el motiu.

Aquest disseny té una conseqüència important que sorprèn molts responsables de programes:

  • L’asserció allotjada és la font de veritat. Qualsevol persona que verifiqui la credencial obtenint la URL de l’asserció o obrint la pàgina de verificació veu l’estat de revocada a l’instant.
  • Les còpies no es retiren. Si el destinatari va baixar la imatge de la insígnia o el JSON, o l’ha fixat en un portfolio, aquest fitxer no canvia. Continua contenint un enllaç a la teva asserció allotjada, de manera que un verificador que segueixi l’enllaç veurà que està revocada, però una persona que només miri un PNG desat no ho veurà.

Per tant, la revocació és una declaració feta al punt de verificació, no una supressió. Pensa-hi com estampar «NUL» sobre el registre original en lloc de perseguir cada fotocòpia.

Si vols mirar de prop el document en si, la nostra guia del JSON-LD d’Open Badge repassa cada camp.

Revocar, tornar a emetre o eliminar: tria l’acció correcta

Abans de fer clic a res, decideix quina de les tres accions encaixa amb la situació. No són intercanviables.

SituacióMillor accióPer què
La credencial es va emetre a la persona equivocada o amb una erradaEliminar (si no s’ha enviat mai) o Revocar i tornar a emetreEliminar esborra el registre del tot; revocar conserva un rastre d’auditoria
L’alumne va incomplir una política o la credencial es va obtenir de manera indegudaRevocar, amb un motiuEl registre continua sent verificable com a revocat, que és el que vols en una disputa
La credencial simplement ha arribat a la data de fiNo facis res; defineix una caducitat quan l’emetisLa caducitat és un fet normal del cicle de vida, no una revocació
Programa cancel·lat, cohort anul·ladaRevocació massivaUna tasca, un motiu, aplicat a tothom
Les dades eren errònies però la credencial és vàlida en la restaEdita-la abans d’enviar-la, o revoca-la i torna-la a emetre si ja s’ha enviatManté neta l’experiència del destinatari

Dues regles pràctiques:

  1. Prefereix revocar a eliminar per a tot el que sigui real. La pàgina pública d’una credencial eliminada retorna un error de «no trobat». Una de revocada continua resolent-se i diu clarament que està revocada, cosa que és una prova molt millor si algú pregunta després què va passar.
  2. No facis servir mai la revocació com a substitut de la caducitat. Si una credencial només és vàlida durant dos anys, defineix-ne la data de caducitat quan l’emetis. Una insígnia que caduca discretament no és el mateix que una que s’ha retirat, i la teva pàgina de verificació ho ha de dir.

Revocar des del tauler

Per a unes poques credencials, el tauler és la via més ràpida i no cal escriure codi.

  1. Inicia la sessió i obre Awards a la barra lateral.
  2. Troba la credencial. La llista mostra el destinatari, el nom de la insígnia, la data d’emissió i la caducitat, i pots cercar per destinatari.
  3. Fes clic a la fila (o a View) per obrir el modal de detall de la credencial.
  4. Fes clic a Revoke.
  5. Al diàleg de confirmació, escriu opcionalment un motiu i marca opcionalment Email the recipient that their credential was revoked.
  6. Confirma.

Award detail modal

La credencial continua a la teva llista amb una etiqueta vermella Revoked al costat del destinatari, de manera que tu i el teu equip sempre podeu veure què s’ha retirat. Revocar no et retorna la credencial a la quota del teu pla. La vas emetre, va comptar.

Una nota sobre el camp del motiu

El motiu és opcional, però omple’l. Es desa amb la credencial, apareix com a revocationReason a l’asserció pública d’Open Badges i s’inclou a la càrrega del webhook que reben els teus sistemes. Com que és públic a l’asserció, escriu-lo pensant en un lector extern. «Emesa per error» o «Programa cancel·lat» està bé. «La Jane va fer trampes a la pregunta 14» no. Guarda els detalls personals als teus propis registres i mantén el motiu públic neutre.

Cal enviar un correu al destinatari?

Normalment sí. Un alumne que s’assabenta que la seva credencial ja no val només quan un empresari fa clic a l’enllaç de verificació té tot el dret a enfadar-se amb tu. La notificació és opcional precisament perquè algunes revocacions (una neteja massiva de premis de prova, per exemple) no cal que molestin ningú. El nostre consell:

  • Envia el correu quan la revocació afecti una persona real que potser encara mostra la credencial.
  • Omet el correu quan estiguis endreçant dades internes de prova o anul·lant credencials que no es van arribar a enviar.

Revocar moltes credencials alhora

Els programes rarament necessiten revocar una credencial aïllada; el més habitual és tota una cohort. A la llista d’Awards:

  1. Marca les caselles de les credencials que vols retirar.
  2. Fes clic a Revoke selected a la barra d’accions massives.
  3. Afegeix un motiu i decideix si vols notificar els destinataris; després confirma.

La revocació massiva s’executa com una tasca duradora en segon pla, de manera que unes quantes centenars de credencials no faran caducar la pestanya del navegador. Les credencials que ja estan revocades se salten en lloc de fer fallar el lot, i una tasca interrompuda a mig camí es pot reprendre. El mateix mecanisme impulsa l’emissió massiva des d’un full de càlcul, que expliquem a com emetre Open Badges des d’un CSV.

Revocar mitjançant l’API

Si el teu sistema d’aprenentatge o la plataforma de RH decideix qui ja no està certificat, pots revocar de manera programàtica. El punt final és POST /awards/{awardId}/revoke, autenticat amb una clau d’API (X-Api-Key: bws_<32-hex>) o un token Bearer de Cognito. L’ID de l’award va al camí; reason i notify van al cos JSON i tots dos són opcionals.

Amb 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>"}

En 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

I en 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

Alguns detalls pràctics que convé conèixer:

  • És idempotent. Revocar una credencial que ja està revocada retorna la mateixa resposta d’èxit i no envia una segona notificació. Això la fa segura per cridar des d’una tasca amb reintents.
  • Els motius es trunquen a 500 caràcters.
  • notify és false per defecte. No s’envia cap correu tret que ho demanis.
  • La revocació massiva està disponible mitjançant el punt final massiu amb action: "revoke" i una llista d’ID d’awards; retorna un ID de tasca que pots seguir. Els paràmetres complets són a la referència de l’API d’awards.

Només necessites l’API quan la revocació la impulsa un altre sistema. Per a un cas puntual, el tauler és més ràpid i té un pas de confirmació que et protegeix d’un ID mal escrit.

Què veuen el destinatari i el verificador

Després de revocar, això és el que canvia i amb quina rapidesa.

A la pàgina pública de verificació. La pàgina a https://badges.ninja/awards/<award-id> mostra la credencial com a revocada, i el títol de la pàgina per compartir a les xarxes socials porta el prefix «[Revoked]» perquè un enllaç compartit no sembli una credencial vigent en una targeta de previsualització.

A l’asserció d’Open Badges v2.0. El JSON allotjat a https://api.badges.ninja/certify-badge/award/<award-id> ara porta "revoked": true, més "revocationReason" si en vas donar un. Les assercions revocades només es guarden a la memòria cau uns 30 segons, mentre que les vigents hi són cinc minuts, de manera que el canvi arriba ràpidament als verificadors.

A la credencial d’Open Badges 3.0. La revocació també canvia el bit de la credencial en una W3C Bitstring Status List, que és com la detecten les carteres i els verificadors de credencials verificables. Aquesta llista es guarda breument a la memòria cau, així que compta amb una propagació d’aproximadament un minut. Si estàs valorant les dues versions, consulta Open Badges v2 vs v3.

A la còpia pròpia del destinatari. No canvia res al fitxer que va baixar. La imatge de la insígnia al seu portàtil té exactament el mateix aspecte. El que canvia és el resultat de la verificació: qualsevol persona que faci clic a l’enllaç o comprovi la credencial de manera programàtica obté la resposta de revocada. Si els vas notificar, també tenen un correu que n’explica el motiu.

A LinkedIn. Una credencial afegida a un perfil de LinkedIn és un enllaç amb metadades que apunta a la teva pàgina de verificació. LinkedIn no consulta periòdicament la revocació per tu, de manera que l’entrada pot continuar al perfil, però qui segueixi l’enllaç arribarà a la pàgina de revocada. Aquest és un altre motiu per enviar la notificació i demanar al destinatari que elimini l’entrada.

Avisa els teus propis sistemes: webhooks

La revocació rarament és el final de la història dins la teva organització. Potser l’alumne ha de perdre l’accés a una comunitat, s’ha d’actualitzar un registre d’ocupador o s’ha de treure una etiqueta del CRM. Badges Ninja emet un esdeveniment de webhook credential.revoked quan es revoca una credencial, amb la URL de l’award i el motiu:

{
  "awardId": "https://api.badges.ninja/certify-badge/award/<award-id>",
  "reason": "Issued in error"
}

Subscriu-t’hi i els teus sistemes posteriors es mantenen sincronitzats sense que ningú hagi de recordar d’actualitzar-los. Els detalls de configuració són a la documentació dels webhooks, i expliquem el model d’esdeveniments més ampli a configuració de webhooks per a esdeveniments d’insígnies.

Una política de revocació senzilla que pots adoptar avui

Les eines són la part fàcil. La part difícil és decidir per endavant quan revocaràs i qui té permís per fer-ho. Una política escrita breu evita discussions més endavant. Una plantilla que funciona:

  1. Motius de revocació. Enumera’ls: emesa per error, obtinguda per mala conducta, requisit que ja no es compleix (per exemple, una afiliació caducada) o programa retirat.
  2. Qui decideix. Anomena un rol, no una persona. Limita el permís de revocar a aquest rol.
  3. Avís. Indica que els destinataris reben un correu amb el motiu, tret que la credencial no s’hagi arribat a lliurar.
  4. Apel·lació. Dona als destinataris una manera d’impugnar la decisió i digues quant trigaràs a respondre. Si una apel·lació prospera, emet una credencial nova en lloc de provar de desfer la revocació, i l’historial es manté net.
  5. Registre. Guarda una nota interna de qui va revocar què i per què, separada del motiu públic neutre.

Publica la política a la mateixa pàgina on descrius la credencial, perquè qui l’obtingui conegui les regles abans d’inscriure’s.

Errors habituals que cal evitar

  • Eliminar quan volies revocar. Eliminar és permanent i no es pot desfer, i fa desaparèixer la pàgina pública. Fes-ho servir per a errades genuïnes en credencials que ningú ha vist.
  • Posar detalls privats al motiu. És públic a l’asserció.
  • Esperar que les còpies desades canviïn. La revocació viu al punt de verificació. Digues als destinataris que eliminin la credencial dels perfils i portfolis.
  • Revocar en lloc de fer caducar. Fes servir una data de caducitat per a les credencials limitades en el temps.
  • Suposar un reemborsament. Les credencials revocades continuen comptant contra la quota del teu pla.
  • Oblidar els sistemes posteriors. Configura el webhook perquè els accessos i els registres segueixin l’estat de la credencial.

Preguntes freqüents

Puc desfer una revocació? No des de la interfície. Si has revocat per error, emet una credencial nova al destinatari. La revocada es queda com a part del rastre d’auditoria.

El destinatari ha de fer res? No. Si vas triar notificar-lo, rep un correu. Altrament, el canvi es produeix silenciosament a la pàgina de verificació.

Funciona la revocació per a credencials que no es van arribar a enviar? Sí, tot i que per a una credencial no enviada amb un error senzill potser prefereixes editar-la abans d’enviar-la, o eliminar-la si ningú l’ha vista.

Hi ha un límit de quantes puc revocar? La revocació massiva s’executa com una tasca en segon pla que es pot reprendre, de manera que els lots grans es gestionen en una sola operació en lloc d’una a una.

Veuran els empresaris que una credencial ha estat revocada? Qualsevol persona que la verifiqui mitjançant la seva URL pública o asserció veu l’estat de revocada i el motiu, si en vas donar un.

Conclusió

Revocar una Open Badge és una acció petita amb conseqüències reals per a la confiança. Fes-ho des del tauler quan sigui una sola credencial, fes servir la revocació massiva per a una cohort, i recorre a l’API o als webhooks quan la decisió la prengui un altre sistema. Mantén els motius neutrals, notifica les persones que ho han de saber i recorda que la revocació canvia el que veuen els verificadors, no els fitxers que ja són a les mans dels destinataris.

Preparat per emetre la teva primera credencial verificable? Comença gratis a badges.ninja — dissenyador visual, pàgina pública de verificació, certificat en PDF, sortida Open Badge v2.0. Sense targeta de crèdit.

Nacho Coll

Sobre l'autor

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.

Tornar al Blog

Articles Relacionats