Come revocare un Open Badge (e che fine fa la copia del destinatario)
La revoca negli Open Badges: come funziona, cosa cambia per il destinatario e come gestire correttamente i casi «emesso per errore», «credenziale scaduta» e «violazione delle regole».
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.
Prima o poi ogni programma che emette credenziali digitali deve ritirarne una. Un attestato è finito alla persona sbagliata. Si scopre che un corsista ha copiato all’esame finale. Il contratto con un partner è scaduto e i badge con la scritta «Certified Partner» non devono più essere validi. Emettere è la parte facile; la revoca è ciò che decide se le tue credenziali sono davvero affidabili.
Questa guida spiega come funziona la revoca negli Open Badges, cosa vede e cosa non vede il destinatario dopo la revoca, e come revocare una credenziale o qualche centinaio di credenziali su https://badges.ninja, dalla dashboard o tramite API.
Cosa significa «revocare» negli Open Badges
Nella specifica Open Badges v2.0, ogni badge emesso è una assertion: un piccolo documento JSON-LD ospitato a un URL pubblico che dice «questa emittente ha assegnato questo badge a questo destinatario in questa data». La revoca è semplicemente una modifica a quel documento ospitato. All’assertion viene aggiunto "revoked": true e, facoltativamente, una stringa "revocationReason" che ne spiega il motivo.
Questo design ha una conseguenza importante che sorprende molti responsabili di programma:
- L’assertion ospitata è la fonte di verità. Chiunque verifichi la credenziale aprendo l’URL dell’assertion o la pagina di verifica vede subito lo stato di revoca.
- Le copie non vengono richiamate. Se il destinatario ha scaricato l’immagine del badge o il JSON, o l’ha inserito in un portfolio, quel file non cambia. Contiene ancora un link alla tua assertion ospitata, quindi un verificatore che lo segue vedrà che è revocata, ma chi dà un’occhiata a un PNG salvato non se ne accorgerà.
La revoca è quindi una dichiarazione fatta all’endpoint di verifica, non una cancellazione. Pensala come un timbro «ANNULLATO» sul registro originale, invece di rincorrere ogni fotocopia.
Se vuoi guardare da vicino il documento, la nostra guida al JSON-LD di Open Badge passa in rassegna ogni campo.
Revocare, riemettere o eliminare: scegli l’azione giusta
Prima di cliccare, decidi quale delle tre azioni si adatta alla situazione. Non sono intercambiabili.
| Situazione | Azione migliore | Perché |
|---|---|---|
| La credenziale è stata emessa alla persona sbagliata o con un refuso | Elimina (se mai inviata) oppure Revoca, poi riemetti | L’eliminazione rimuove del tutto il record; la revoca mantiene una traccia di audit |
| Il corsista ha violato una regola o la credenziale è stata ottenuta in modo scorretto | Revoca, con un motivo | Il record resta verificabile come revocato, ed è ciò che serve in caso di contestazione |
| La credenziale ha semplicemente raggiunto la data di fine | Non fare nulla; imposta una scadenza all’emissione | La scadenza è un normale evento del ciclo di vita, non una revoca |
| Programma annullato, coorte invalidata | Revoca in blocco | Un’unica operazione, un unico motivo, applicato a tutti |
| I dati erano sbagliati ma la credenziale è per il resto valida | Modifica prima dell’invio, oppure revoca e riemetti dopo l’invio | Mantiene pulita l’esperienza del destinatario |
Due regole pratiche:
- Per qualsiasi credenziale reale, preferisci revocare a eliminare. La pagina pubblica di una credenziale eliminata restituisce un errore di pagina non trovata. Una revocata continua a risolversi e dice chiaramente di essere revocata, il che è una prova molto migliore se qualcuno in seguito chiede cos’è successo.
- Non usare mai la revoca al posto della scadenza. Se una credenziale è valida solo due anni, imposta una data di scadenza quando la emetti. Un badge che decade in silenzio è diverso da uno ritirato, e la tua pagina di verifica deve dire quale dei due è.
Revocare dalla dashboard
Per poche credenziali, la dashboard è la via più rapida e non richiede codice.
- Accedi e apri Awards dalla barra laterale.
- Trova la credenziale. L’elenco mostra destinatario, nome del badge, data di emissione e scadenza, e puoi cercare per destinatario.
- Clicca sulla riga (o su View) per aprire la finestra di dettaglio della credenziale.
- Clicca su Revoke.
- Nella finestra di conferma, inserisci facoltativamente un motivo e, se vuoi, spunta Email the recipient that their credential was revoked.
- Conferma.

La credenziale resta nel tuo elenco con un’etichetta rossa Revoked accanto al destinatario, così tu e il tuo team potete sempre vedere cosa è stato ritirato. La revoca non restituisce la credenziale alla quota del tuo piano. L’hai emessa, quindi è stata conteggiata.
Una nota sul campo del motivo
Il motivo è facoltativo, ma compilalo. Viene salvato con la credenziale, compare come revocationReason nell’assertion pubblica Open Badges ed è incluso nel payload del webhook che ricevono i tuoi sistemi. Poiché è pubblico nell’assertion, scrivilo come lo scriveresti per un lettore esterno. «Emesso per errore» o «Programma annullato» vanno bene. «Jane ha copiato alla domanda 14» no. Tieni i dettagli personali nei tuoi archivi e mantieni neutro il motivo pubblico.
Conviene avvisare il destinatario via email?
Di solito sì. Un corsista che scopre che la sua credenziale non vale più solo perché un datore di lavoro clicca sul link di verifica ha ogni diritto di essere arrabbiato con te. La notifica è opzionale proprio perché alcune revoche (per esempio una pulizia in blocco di premi di prova) non hanno bisogno di disturbare nessuno. Il nostro consiglio:
- Invia l’email quando la revoca riguarda una persona reale che potrebbe ancora mostrare la credenziale.
- Salta l’email quando stai riordinando dati di test interni o annullando credenziali mai inviate.
Revocare molte credenziali in una volta
Raramente un programma deve revocare una credenziale isolata; più spesso si tratta di un’intera coorte. Nell’elenco Awards:
- Spunta le caselle delle credenziali che vuoi ritirare.
- Clicca su Revoke selected nella barra delle azioni in blocco.
- Aggiungi un motivo, decidi se avvisare i destinatari e conferma.
La revoca in blocco viene eseguita come job in background duraturo, quindi qualche centinaio di credenziali non manderà in timeout la scheda del browser. Le credenziali già revocate vengono saltate invece di far fallire il lotto, e un job interrotto a metà può essere ripreso. Lo stesso meccanismo alimenta l’emissione in blocco da foglio di calcolo, di cui parliamo in come emettere Open Badges da un CSV.
Revocare tramite API
Se è il tuo sistema di apprendimento o la tua piattaforma HR a decidere chi non è più certificato, puoi revocare in modo programmatico. L’endpoint è POST /awards/{awardId}/revoke, autenticato con una chiave API (X-Api-Key: bws_<32-hex>) o un token Bearer Cognito. L’ID dell’award va nel percorso; reason e notify vanno nel corpo JSON ed entrambi sono facoltativi.
Con 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>"}
In 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
E in 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
Alcuni dettagli pratici da conoscere:
- È idempotente. Revocare una credenziale già revocata restituisce la stessa risposta di successo e non invia una seconda notifica. Per questo è sicuro chiamarla da un job con tentativi automatici.
- I motivi vengono troncati a 500 caratteri.
notifyè false per impostazione predefinita. Non viene inviata alcuna email se non lo chiedi.- La revoca in blocco è disponibile tramite l’endpoint bulk con
action: "revoke"e un elenco di ID award; restituisce un ID di job che puoi monitorare. I parametri completi sono nel riferimento API degli awards.
L’API serve solo quando la revoca è guidata da un altro sistema. Per un caso singolo, la dashboard è più rapida e ha un passaggio di conferma che ti protegge da un ID digitato male.
Cosa vedono il destinatario e il verificatore
Dopo la revoca, ecco cosa cambia e con quale rapidità.
Nella pagina pubblica di verifica. La pagina https://badges.ninja/awards/<award-id> mostra la credenziale come revocata, e il titolo della pagina per la condivisione social è preceduto da «[Revoked]», così un link condiviso non sembra una credenziale attiva in un’anteprima.
Nell’assertion Open Badges v2.0. Il JSON ospitato su https://api.badges.ninja/certify-badge/award/<award-id> ora contiene "revoked": true, più "revocationReason" se l’hai indicato. Le assertion revocate vengono messe in cache solo per circa 30 secondi, mentre quelle attive per cinque minuti, quindi la modifica raggiunge in fretta i verificatori.
Nella credenziale Open Badges 3.0. La revoca modifica anche il bit della credenziale in una W3C Bitstring Status List, ed è così che wallet e verificatori di verifiable credential la rilevano. Questa lista è messa in cache per poco tempo, quindi aspettati una propagazione entro circa un minuto. Se stai valutando le due versioni, leggi Open Badges v2 vs v3.
Nella copia del destinatario. Sul file che ha scaricato non cambia nulla. L’immagine del badge sul suo portatile ha lo stesso aspetto. Cambia l’esito della verifica: chiunque clicchi sul link o controlli la credenziale in modo programmatico ottiene la risposta «revocata». Se l’hai avvisato, ha anche un’email che ne spiega il motivo.
Su LinkedIn. Una credenziale aggiunta a un profilo LinkedIn è un link con metadati che rimanda alla tua pagina di verifica. LinkedIn non controlla le revoche al posto tuo, quindi la voce può restare sul profilo, ma chi segue il link arriva alla pagina di revoca. È un altro motivo per inviare la notifica e chiedere al destinatario di rimuovere la voce.
Avvisa i tuoi sistemi: i webhook
La revoca raramente è la fine della storia all’interno della tua organizzazione. Il corsista potrebbe dover perdere l’accesso a una community, il record di un datore di lavoro potrebbe richiedere un aggiornamento o un tag del CRM andrebbe rimosso. Badges Ninja emette un evento webhook credential.revoked quando una credenziale viene revocata, con l’URL dell’award e il motivo:
{
"awardId": "https://api.badges.ninja/certify-badge/award/<award-id>",
"reason": "Issued in error"
}
Iscriviti all’evento e i tuoi sistemi a valle restano allineati senza che nessuno debba ricordarsi di aggiornarli. I dettagli di configurazione sono nella documentazione dei webhook, e il modello più ampio degli eventi lo trattiamo in configurare i webhook per gli eventi dei badge.
Una semplice policy di revoca che puoi adottare oggi
Gli strumenti sono la parte facile. La parte più difficile è decidere in anticipo quando revocherai e chi può farlo. Una breve policy scritta evita discussioni in seguito. Un modello funzionante:
- Motivi di revoca. Elencali: emessa per errore, ottenuta con scorrettezza, requisito non più soddisfatto (per esempio un’iscrizione scaduta) o programma ritirato.
- Chi decide. Indica un ruolo, non una persona. Limita il permesso di revoca a quel ruolo.
- Comunicazione. Specifica che i destinatari vengono avvisati via email, con il motivo, a meno che la credenziale non sia mai stata consegnata.
- Ricorso. Offri ai destinatari un modo per contestare la decisione e indica in quanto tempo risponderai. Se il ricorso viene accolto, riemetti una credenziale nuova invece di provare ad annullare la revoca: lo storico resta pulito.
- Registro. Conserva una nota interna di chi ha revocato cosa e perché, separata dal motivo pubblico neutro.
Pubblica la policy nella stessa pagina in cui descrivi la credenziale, così chi la ottiene conosce le regole prima di iscriversi.
Errori comuni da evitare
- Eliminare quando volevi revocare. L’eliminazione è permanente, non si può annullare e fa sparire la pagina pubblica. Usala per errori veri su credenziali che nessuno ha visto.
- Mettere dettagli privati nel motivo. È pubblico nell’assertion.
- Aspettarsi che le copie salvate cambino. La revoca vive all’endpoint di verifica. Di’ ai destinatari di rimuovere la credenziale da profili e portfolio.
- Revocare invece di far scadere. Usa una data di scadenza per le credenziali a tempo.
- Dare per scontato un rimborso. Le credenziali revocate contano comunque sulla quota del tuo piano.
- Dimenticare i sistemi a valle. Collega il webhook così accessi e record seguono lo stato della credenziale.
Domande frequenti
Posso annullare una revoca? Non dall’interfaccia. Se hai revocato per sbaglio, emetti una nuova credenziale al destinatario. Quella revocata resta come parte della traccia di audit.
Il destinatario deve fare qualcosa? No. Se hai scelto di avvisarlo, riceve un’email. Altrimenti la modifica avviene in silenzio nella pagina di verifica.
La revoca funziona per credenziali mai inviate? Sì, anche se per una credenziale non inviata con un semplice errore potresti preferire modificarla prima dell’invio, o eliminarla se nessuno l’ha vista.
C’è un limite a quante ne posso revocare? La revoca in blocco viene eseguita come job in background riprendibile, quindi i lotti grandi vengono gestiti in una sola operazione invece che una alla volta.
I datori di lavoro vedranno che una credenziale è stata revocata? Chiunque la verifichi tramite il suo URL pubblico o l’assertion vede lo stato di revoca e il motivo, se l’hai indicato.
Conclusione
Revocare un Open Badge è un gesto piccolo con conseguenze reali sulla fiducia. Fallo dalla dashboard quando è una singola credenziale, usa la revoca in blocco per una coorte e ricorri all’API o ai webhook quando è un altro sistema a decidere. Mantieni neutri i motivi, avvisa chi deve saperlo e ricorda che la revoca cambia ciò che vedono i verificatori, non i file già nelle mani dei destinatari.
Pronto a emettere la tua prima credenziale verificabile? Inizia gratis su badges.ninja — designer visuale, pagina pubblica di verifica, certificato PDF, output Open Badge v2.0. Nessuna carta di credito richiesta.
Come è stato realizzato questo articolo
Alcuni articoli di questo blog vengono redatti con l'aiuto di un assistente IA e poi revisionati, verificati e modificati dal team di Badges Ninja prima della pubblicazione. Ogni esempio di codice e ogni prezzo viene verificato rispetto al prodotto live. Scopri di più sul nostro processo editoriale e sull'uso dell'IA nella nostra pagina sul processo editoriale .

Informazioni sull'autore
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.
Altri articoli di Nacho Coll
- Open Badges per i bootcamp di coding: emettere credenziali verificabili su scala di coorte19 nov 2026 · 12min di lettura
- Configurare i webhook per gli eventi dei badge: integrazione in tempo reale con il tuo backend16 nov 2026 · 9min di lettura
- Scadenza e rinnovo degli Open Badge: gestire il ciclo di vita delle credenziali a tempo12 nov 2026 · 12min di lettura


