Kuidas Open Badge tühistada (ja mis saab saaja koopiast)
Tühistamine Open Badgesis: kuidas see töötab, mis muutub saaja jaoks ja kuidas käsitleda õigesti olukordi „välja antud ekslikult“, „volitus aegus“ ja „reeglite rikkumine“.
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.
Enne või hiljem peab iga digitaalseid volitusi välja andev programm mõne neist tagasi võtma. Sertifikaat läks valele inimesele. Selgus, et õppija petis lõpuhindamisel. Partnerleping lõppes ja märgid, millel seisis „Certified Partner“, ei tohiks enam kehtida. Väljaandmine on lihtne osa; tühistamine on see, mis otsustab, kas sinu volitusi saab tegelikult usaldada.
See juhend selgitab, kuidas tühistamine Open Badgesis töötab, mida saaja pärast näeb ja mida mitte, ning kuidas tühistada ühte volitust või paarisadat aadressil https://badges.ninja, töölaualt või API kaudu.
Mida tähendab Open Badgesis „tühistada“
Open Badges v2.0 spetsifikatsioonis on iga välja antud märk kinnitus (assertion): väike JSON-LD dokument avalikul URL-il, mis ütleb: „see väljaandja andis selle märgi sellele saajale sel kuupäeval.“ Tühistamine on lihtsalt selle majutatud dokumendi muutmine. Kinnitus saab väärtuse "revoked": true ja soovi korral stringi "revocationReason", mis põhjendab otsust.
Sellel lahendusel on oluline tagajärg, mis paljusid programmi omanikke üllatab:
- Majutatud kinnitus on tõe allikas. Igaüks, kes kontrollib volitust kinnituse URL-i päringuga või kinnitamislehe avamisega, näeb tühistatud olekut kohe.
- Koopiaid tagasi ei kutsuta. Kui saaja laadis märgi pildi või JSON-i alla või kinnitas selle portfooliosse, see fail ei muutu. Selles on endiselt link sinu majutatud kinnituse juurde, nii et linki järgiv kontrollija näeb tühistamist, kuid salvestatud PNG-d vilksamisi vaatav inimene mitte.
Tühistamine on seega avaldus kinnitamise lõpp-punktis, mitte kustutamine. Mõtle sellest kui põhikirjele templi „VOID“ vajutamisest, mitte iga koopia taga ajamisest.
Kui tahad dokumenti lähemalt uurida, käib meie Open Badge JSON-LD ülevaade iga välja läbi.
Tühistada, uuesti välja anda või kustutada: vali õige tegevus
Enne kui midagi klõpsad, otsusta, milline kolmest tegevusest olukorda sobib. Need pole omavahel asendatavad.
| Olukord | Parim tegevus | Miks |
|---|---|---|
| Volitus anti valele inimesele või sisaldab trükiviga | Kustuta (kui pole saadetud) või tühista ja anna uuesti välja | Kustutamine eemaldab kirje täielikult; tühistamine säilitab auditijälje |
| Õppija rikkus reegleid või volitus saadi ebaõiglasel teel | Tühista põhjusega | Kirje jääb tühistatuna kontrollitavaks, mida vaidluses vajad |
| Volitus lihtsalt jõudis lõppkuupäevani | Ära tee midagi; määra väljaandmisel aegumine | Aegumine on tavaline elutsükli sündmus, mitte tühistamine |
| Programm tühistati, kohort muudeti kehtetuks | Hulgi tühistamine | Üks töö, üks põhjus, kõigile rakendatud |
| Andmed olid valed, kuid volitus on muidu kehtiv | Muuda enne saatmist või tühista ja anna pärast saatmist uuesti välja | Hoiab saaja kogemuse puhta |
Kaks rusikareeglit:
- Päris volituste puhul eelista tühistamist kustutamisele. Kustutatud volituse avalik leht annab vea „ei leitud“. Tühistatud leht avaneb siiski ja ütleb selgelt, et see on tühistatud, mis on palju parem tõend, kui keegi hiljem küsib, mis juhtus.
- Ära kasuta tühistamist aegumise asemel. Kui volitus kehtib vaid kaks aastat, määra väljaandmisel aegumiskuupäev. Vaikselt aeguv märk erineb tagasi võetud märgist ja sinu kinnitamisleht peaks ütlema, kumb see on.
Tühistamine töölaualt
Mõne volituse puhul on töölaud kiireim tee ega vaja koodi.
- Logi sisse ja ava külgribalt Awards.
- Leia volitus. Loend näitab saajat, märgi nime, väljaandmise kuupäeva ja aegumist ning saajat saab otsida.
- Klõpsa reale (või View), et avada volituse üksikasjade aken.
- Klõpsa Revoke.
- Kinnitusdialoogis sisesta soovi korral põhjus ja märgi soovi korral Email the recipient that their credential was revoked.
- Kinnita.

Volitus jääb sinu loendisse punase Revoked märgiga saaja kõrval, nii et sina ja sinu meeskond näete alati, mis on tagasi võetud. Tühistamine ei tagasta volitust sinu paketi kvoodis. Sa andsid selle välja, see läks arvesse.
Märkus põhjuse välja kohta
Põhjus on vabatahtlik, kuid täida see. See salvestatakse volitusega, ilmub avalikus Open Badges kinnituses väljana revocationReason ja kuulub veebikonksu (webhook) andmetesse, mille sinu süsteemid saavad. Kuna see on kinnituses avalik, kirjuta see nii, nagu kirjutaksid kõrvalisele lugejale. „Välja antud ekslikult“ või „Programm tühistati“ sobib. „Jane petis küsimuses 14“ ei sobi. Hoia isiklikud üksikasjad oma andmetes ja avalik põhjus neutraalne.
Kas saajale e-kiri saata?
Tavaliselt jah. Õppijal, kes saab oma volituse surnuks olemisest teada alles siis, kui tööandja klõpsab kinnituslinki, on täielik õigus sinu peale pahane olla. Teavitus on vabatahtlik just seetõttu, et mõni tühistamine (näiteks testauhindade hulgipuhastus) ei vaja kellegi tülitamist. Meie soovitus:
- Saada e-kiri, kui tühistamine puudutab päris inimest, kes võib volitust endiselt kuvada.
- Jäta e-kiri saatmata, kui koristad sisemisi testandmeid või muudad kehtetuks volitusi, mida ei saadetud kunagi.
Paljude volituste tühistamine korraga
Programmid vajavad harva ühe volituse tühistamist üksinda; sagedamini on tegu tervikliku kohordiga. Awards loendis:
- Märgi ruudud nende volituste juures, mida tahad tagasi võtta.
- Klõpsa hulgitegevuste ribal Revoke selected.
- Lisa põhjus ja otsusta, kas saajaid teavitada, seejärel kinnita.
Hulgi tühistamine töötab vastupidava taustatööna, nii et paarisadat volitust ei aegu sinu brauseri vahekaardil. Juba tühistatud volitused jäetakse vahele, mitte ei lase partii ebaõnnestuda, ja poolelijäänud töö saab jätkata. Sama mehhanism toetab hulgi väljaandmist tabelist, mida kirjeldame artiklis kuidas anda Open Badges CSV-st välja.
Tühistamine API kaudu
Kui sinu õppesüsteem või personaliplatvorm otsustab, kes pole enam sertifitseeritud, saad tühistada programmiliselt. Lõpp-punkt on POST /awards/{awardId}/revoke, autentimine API võtmega (X-Api-Key: bws_<32-hex>) või Cognito Bearer-tokeniga. Award ID läheb teele; reason ja notify lähevad JSON-i kehasse ning mõlemad on valikulised.
curl-iga:
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>"}
JavaScriptis:
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
Ja Pythonis:
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
Mõned praktilised detailid:
- See on idempotentne. Juba tühistatud volituse tühistamine tagastab sama edukas vastuse ega saada teist teavitust. See muudab selle turvaliseks korduskatsetega töös.
- Põhjused lõigatakse 500 märgini.
notifyon vaikimisi false. E-kirja ei saadeta, kui sa ei palu.- Hulgi tühistamine on saadaval hulgi-lõpp-punkti kaudu parameetriga
action: "revoke"ja award ID-de loendiga; see tagastab töö ID, mida saad jälgida. Kõik parameetrid on awards API viites.
API-t on vaja vaid siis, kui tühistamist juhib mõni teine süsteem. Ühekordseks tegevuseks on töölaud kiirem ja sisaldab kinnitusetappi, mis kaitseb valesti sisestatud ID eest.
Mida näevad saaja ja kontrollija
Pärast tühistamist muutub järgmine ja nii kiiresti.
Avalikul kinnitamislehel. Leht aadressil https://badges.ninja/awards/<award-id> näitab volitust tühistatuna ja sotsiaalmeedias jagamise lehepealkirjale lisatakse ette „[Revoked]“, et jagatud link ei näeks eelvaatekaardil välja nagu kehtiv volitus.
Open Badges v2.0 kinnituses. Majutatud JSON aadressil https://api.badges.ninja/certify-badge/award/<award-id> sisaldab nüüd "revoked": true ning "revocationReason", kui andsid põhjuse. Tühistatud kinnitusi puhverdatakse vaid umbes 30 sekundit, kehtivaid aga viis minutit, nii et muudatus jõuab kontrollijateni kiiresti.
Open Badges 3.0 volituses. Tühistamine pöörab ümber ka volituse biti W3C Bitstring Status Listis, mille kaudu kontrollitavate volituste rahakotid ja kontrollijad selle tuvastavad. Seda loendit puhverdatakse lühidalt, nii et oota levimist umbes minutiga. Kui kaalud kahte versiooni, vaata Open Badges v2 vs v3.
Saaja enda koopias. Allalaaditud failil ei muutu midagi. Märgi pilt tema sülearvutis näeb välja sama. Muutub kontrollimise tulemus: igaüks, kes linki klõpsab või volitust programmiliselt kontrollib, saab vastuseks „tühistatud“. Kui teavitasid teda, on tal ka e-kiri, mis põhjendab.
LinkedInis. LinkedIni profiilile lisatud volitus on link koos metaandmetega, mis viitab tagasi sinu kinnitamislehele. LinkedIn ei küsi sinu eest tühistamisi, nii et kirje võib profiilile jääda, kuid igaüks, kes linki järgib, jõuab tühistatud lehele. See on veel üks põhjus teavitus saata ja paluda saajal kirje eemaldada.
Anna oma süsteemidele teada: veebikonksud
Tühistamine pole organisatsioonis harva lugu lõpp. Õppija võib kaotada ligipääsu kogukonnale, tööandja kirjet tuleb uuendada või CRM-i silt eemaldada. Badges Ninja saadab volituse tühistamisel veebikonksu sündmuse credential.revoked koos award URL-i ja põhjusega:
{
"awardId": "https://api.badges.ninja/certify-badge/award/<award-id>",
"reason": "Issued in error"
}
Telli see ja sinu allavoolu süsteemid püsivad sammus, ilma et keegi peaks uuendamist meeles pidama. Seadistuse üksikasjad on veebikonksude dokumentatsioonis ja laiemat sündmusemudelit käsitleme artiklis veebikonksude seadistamine märgi sündmustele.
Lihtne tühistamispoliitika, mille saad kasutusele võtta juba täna
Tööriistad on lihtsam pool. Raskem pool on ette otsustada, millal tühistad ja kellel on selleks õigus. Lühike kirjalik poliitika hoiab hilisemad vaidlused ära. Toimiv mall:
- Tühistamise alused. Loetle need: välja antud ekslikult, saadud eksimuse teel, nõue pole enam täidetud (näiteks liikmelisus lõppes) või programm kaotati.
- Kes otsustab. Nimeta roll, mitte inimene. Piira tühistamisõigus selle rolliga.
- Teavitus. Maini, et saajaid teavitatakse e-kirjaga koos põhjusega, välja arvatud juhul, kui volitust ei toimetatud kunagi kätte.
- Edasikaebus. Anna saajatele võimalus otsust vaidlustada ja ütle, kui kaua vastamine aega võtab. Kui edasikaebus õnnestub, anna välja uus volitus, mitte ei püüa tühistamist tagasi pöörata, ja ajalugu jääb puhtaks.
- Kirje. Pea sisemist märget, kes mida ja miks tühistas, eraldi neutraalsest avalikust põhjusest.
Avalda poliitika samal lehel, kus kirjeldad volitust, et teenijad teaksid reegleid enne registreerumist.
Levinud vead, mida vältida
- Kustutamine, kui mõtlesid tühistamist. Kustutamine on püsiv ja seda ei saa tagasi võtta ning avalik leht kaob. Kasuta seda päris vigade jaoks volitustel, mida keegi pole näinud.
- Privaatsed üksikasjad põhjuses. See on kinnituses avalik.
- Ootus, et salvestatud koopiad muutuvad. Tühistamine elab kinnitamise lõpp-punktis. Palu saajatel volitus profiilidelt ja portfoolioitest eemaldada.
- Tühistamine aegumise asemel. Ajaliselt piiratud volituste jaoks kasuta aegumiskuupäeva.
- Tagasimakse eeldamine. Tühistatud volitused loevad endiselt sinu paketi kvoodi hulka.
- Allavoolu süsteemide unustamine. Ühenda veebikonks, et ligipääsud ja kirjed järgiksid volituse olekut.
Korduma kippuvad küsimused
Kas tühistamise saab tagasi võtta? Mitte liidese kaudu. Kui tühistasid ekslikult, anna saajale välja uus volitus. Tühistatu jääb auditijälje osaks.
Kas saaja peab midagi tegema? Ei. Kui otsustasid teda teavitada, saab ta e-kirja. Muidu toimub muutus vaikselt kinnitamislehel.
Kas tühistamine töötab volituste puhul, mida ei saadetud? Jah, kuigi saatmata volituse lihtsa vea korral võid eelistada seda enne saatmist muuta või kustutada, kui keegi pole seda näinud.
Kas tühistatavate arvule on piirang? Hulgi tühistamine töötab jätkatava taustatööna, nii et suured partiid käsitletakse ühe toiminguna, mitte ükshaaval.
Kas tööandjad näevad, et volitus tühistati? Igaüks, kes seda avaliku URL-i või kinnituse kaudu kontrollib, näeb tühistatud olekut ja põhjust, kui selle andsid.
Kokkuvõte
Open Badge tühistamine on väike tegu, millel on usalduse jaoks tõsised tagajärjed. Tee seda töölaualt, kui tegu on ühe volitusega, kasuta kohordi jaoks hulgi tühistamist ning haara API või veebikonksude järele, kui otsuse omab mõni teine süsteem. Hoia põhjused neutraalsed, teavita neid, kes peavad teadma, ja pea meeles, et tühistamine muudab seda, mida kontrollijad näevad, mitte faile, mis on juba saajate käes.
Valmis andma välja oma esimest kontrollitavat volitust? Alusta tasuta aadressil badges.ninja — visuaalne kujundaja, avalik kinnitusleht, PDF-sertifikaat, Open Badge v2.0 väljund. Krediitkaarti pole vaja.
Kuidas see artikkel valmis
Osa selle blogi postitustest on koostatud tehisintellekti abiga ning seejärel üle vaadatud, faktikontrollitud ja toimetatud Badges Ninja meeskonna poolt enne avaldamist. Iga koodinäide ja hind on kontrollitud reaalse toote vastu. Loe lähemalt meie toimetus- ja AI-protsessi kohta meie toimetusprotsessi lehel .

Autorist
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.
Rohkem autorilt Nacho Coll
- Programmeerimiskooli Open Badges: kontrollitavate tunnistuste väljaandmine terve kohordi mastaabis19. nov 2026 · 9min lugemist
- Veebikonksude seadistamine märgisündmuste jaoks: reaalajas integratsioon sinu taustasüsteemiga16. nov 2026 · 7min lugemist
- Open Badge'i aegumine ja uuendamine: ajaliselt piiratud kvalifikatsioonide elutsükli haldus12. nov 2026 · 9min lugemist


