Een Open Badge intrekken (en wat er met de kopie van de ontvanger gebeurt)

Intrekken in Open Badges: hoe het werkt, wat er verandert voor de ontvanger en hoe je «per ongeluk uitgegeven», «credential verlopen» en «beleidsovertreding» op de juiste manier afhandelt.

Nacho Coll Door Bijgewerkt 10 min leestijd
Intrekken in Open Badges: hoe het werkt, wat er verandert voor de ontvanger en hoe je «per ongeluk uitgegeven», «credential verlopen» en «beleidsovertreding» op de juiste manier afhandelt.

Vroeg of laat moet elk programma dat digitale credentials uitgeeft er een terugnemen. Een certificaat ging naar de verkeerde persoon. Een cursist bleek te hebben gespiekt bij het eindexamen. Een partnercontract eindigde en de badges met «Certified Partner» horen niet meer geldig te zijn. Uitgeven is het gemakkelijke deel; intrekken bepaalt of je credentials echt te vertrouwen zijn.

Deze gids legt uit hoe intrekken werkt in Open Badges, wat de ontvanger daarna wel en niet ziet, en hoe je één credential of enkele honderden intrekt op https://badges.ninja, via het dashboard of de API.

Wat «intrekken» betekent in Open Badges

In de Open Badges v2.0-specificatie is elke uitgegeven badge een assertion: een klein JSON-LD-document op een openbare URL dat zegt: «deze uitgever heeft deze badge op deze datum aan deze ontvanger toegekend.» Intrekken is simpelweg een wijziging in dat gehoste document. De assertion krijgt "revoked": true en optioneel een "revocationReason"-string met de reden.

Dat ontwerp heeft een belangrijk gevolg dat veel programmaverantwoordelijken verrast:

  • De gehoste assertion is de bron van waarheid. Wie de credential verifieert via de assertion-URL of de verificatiepagina, ziet direct de ingetrokken status.
  • Kopieën worden niet teruggehaald. Heeft de ontvanger de badge-afbeelding of de JSON gedownload, of in een portfolio vastgezet, dan verandert dat bestand niet. Het bevat nog steeds een link naar je gehoste assertion, dus een verificateur die die link volgt ziet dat de badge is ingetrokken, maar iemand die even naar een opgeslagen PNG kijkt niet.

Intrekken is dus een mededeling bij het verificatie-endpoint, geen verwijdering. Zie het als een stempel «VOID» op het hoofdrecord, in plaats van elke fotokopie najagen.

Wil je het document zelf beter bekijken? Onze Open Badge JSON-LD-walkthrough loopt elk veld langs.

Intrekken, opnieuw uitgeven of verwijderen: kies de juiste actie

Bepaal voordat je klikt welke van de drie acties bij de situatie past. Ze zijn niet uitwisselbaar.

SituatieBeste actieWaarom
Credential is aan de verkeerde persoon uitgegeven of bevat een typfoutVerwijderen (als nooit verstuurd) of Intrekken, daarna opnieuw uitgevenVerwijderen haalt het record helemaal weg; intrekken bewaart een audittrail
Cursist overtrad het beleid of de credential is onrechtmatig verkregenIntrekken, met een redenHet record blijft verifieerbaar als ingetrokken, precies wat je wilt bij een geschil
Credential heeft gewoon zijn einddatum bereiktNiets doen; stel bij het uitgeven een vervaldatum inVerlopen is een normale gebeurtenis in de levenscyclus, geen intrekking
Programma geannuleerd, cohort ongeldig verklaardBulk intrekkenEén taak, één reden, voor iedereen toegepast
Gegevens waren fout maar de credential is verder geldigBewerken vóór verzenden, of na verzenden intrekken en opnieuw uitgevenHoudt de ervaring van de ontvanger netjes

Twee vuistregels:

  1. Kies bij alles wat echt is liever intrekken dan verwijderen. De openbare pagina van een verwijderde credential geeft een not-found-fout. Een ingetrokken credential blijft bereikbaar en zegt duidelijk dat hij is ingetrokken, wat veel sterker bewijs is als iemand later vraagt wat er gebeurd is.
  2. Gebruik intrekken nooit als vervanging voor verlopen. Is een credential maar twee jaar geldig, stel dan bij het uitgeven een vervaldatum in. Een badge die stilletjes verloopt is iets anders dan een badge die is ingetrokken, en je verificatiepagina hoort aan te geven welke van de twee het is.

Intrekken via het dashboard

Voor een handvol credentials is het dashboard de snelste weg, en je hebt geen code nodig.

  1. Log in en open Awards in de zijbalk.
  2. Zoek de credential. De lijst toont ontvanger, badgenaam, uitgiftedatum en vervaldatum, en je kunt zoeken op ontvanger.
  3. Klik op de rij (of op View) om het detailvenster van de credential te openen.
  4. Klik op Revoke.
  5. Vul in het bevestigingsvenster optioneel een reden in en vink eventueel Email the recipient that their credential was revoked aan.
  6. Bevestig.

Award detail modal

De credential blijft in je lijst staan met een rode Revoked-chip naast de ontvanger, zodat jij en je team altijd kunnen zien wat is ingetrokken. Intrekken geeft de credential niet terug aan het quotum van je abonnement. Je hebt hem uitgegeven, dus hij telde mee.

Een opmerking over het redenveld

De reden is optioneel, maar vul hem in. Hij wordt bij de credential opgeslagen, verschijnt als revocationReason in de openbare Open Badges-assertion en zit in de webhook-payload die je systemen ontvangen. Omdat hij openbaar op de assertion staat, schrijf je hem zoals je voor een buitenstaander zou schrijven. «Per ongeluk uitgegeven» of «Programma geannuleerd» is prima. «Jane heeft gespiekt bij vraag 14» niet. Bewaar persoonlijke details in je eigen administratie en houd de openbare reden neutraal.

Moet je de ontvanger mailen?

Meestal wel. Een cursist die pas hoort dat zijn credential niet meer geldt wanneer een werkgever op de verificatielink klikt, heeft alle recht om boos op je te zijn. De melding is opt-in, juist omdat sommige intrekkingen (bijvoorbeeld een bulkopschoning van testawards) niemand lastig hoeven te vallen. Ons advies:

  • Mail wanneer de intrekking een echt persoon raakt die de credential mogelijk nog toont.
  • Sla de e-mail over wanneer je interne testdata opruimt of credentials ongeldig maakt die nooit zijn verstuurd.

Veel credentials tegelijk intrekken

Programma’s hoeven zelden één credential los in te trekken; vaker gaat het om een heel cohort. In de Awards-lijst:

  1. Vink de selectievakjes aan van de credentials die je wilt intrekken.
  2. Klik op Revoke selected in de balk voor bulkacties.
  3. Voeg een reden toe, bepaal of je ontvangers waarschuwt en bevestig.

Bulk intrekken draait als duurzame achtergrondtaak, dus een paar honderd credentials laten je browsertabblad niet time-outen. Credentials die al zijn ingetrokken worden overgeslagen in plaats van de batch te laten mislukken, en een halverwege onderbroken taak kan worden hervat. Dezelfde machinerie drijft het bulk uitgeven vanuit een spreadsheet aan, dat we behandelen in Open Badges uitgeven vanuit een CSV.

Intrekken via de API

Als je leersysteem of HR-platform bepaalt wie niet langer gecertificeerd is, kun je programmatisch intrekken. Het endpoint is POST /awards/{awardId}/revoke, geauthenticeerd met een API-sleutel (X-Api-Key: bws_<32-hex>) of een Cognito Bearer-token. De award-ID staat in het pad; reason en notify staan in de JSON-body en zijn allebei optioneel.

Met 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

En 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

Een paar praktische details om te weten:

  • Het is idempotent. Een credential die al is ingetrokken opnieuw intrekken geeft hetzelfde succesbericht en verstuurt geen tweede melding. Zo kun je het veilig aanroepen vanuit een taak die opnieuw probeert.
  • Redenen worden afgekapt op 500 tekens.
  • notify staat standaard op false. Er wordt niets gemaild tenzij je erom vraagt.
  • Bulk intrekken kan via het bulk-endpoint met action: "revoke" en een lijst met award-ID’s; je krijgt een job-ID terug dat je kunt volgen. De volledige parameters staan in de awards API-referentie.

Je hebt de API alleen nodig als het intrekken door een ander systeem wordt aangestuurd. Voor een eenmalig geval is het dashboard sneller en heeft het een bevestigingsstap die je behoedt voor een verkeerd getypt ID.

Wat de ontvanger en de verificateur zien

Dit verandert er nadat je hebt ingetrokken, en hoe snel.

Op de openbare verificatiepagina. De pagina op https://badges.ninja/awards/<award-id> toont de credential als ingetrokken, en de paginatitel voor delen op social media krijgt het voorvoegsel «[Revoked]», zodat een gedeelde link in een voorbeeldkaart er niet uitziet als een geldige credential.

In de Open Badges v2.0-assertion. De gehoste JSON op https://api.badges.ninja/certify-badge/award/<award-id> bevat nu "revoked": true, plus "revocationReason" als je een reden hebt opgegeven. Ingetrokken assertions worden maar ongeveer 30 seconden gecachet, terwijl actieve vijf minuten gecachet worden, dus de wijziging bereikt verificateurs snel.

In de Open Badges 3.0-credential. Intrekken zet ook het bit van de credential om in een W3C Bitstring Status List, waarmee wallets en verificateurs van verifiable credentials de intrekking detecteren. Die lijst wordt kort gecachet, dus reken op verspreiding binnen ongeveer een minuut. Als je de twee versies afweegt, lees dan Open Badges v2 vs v3.

In de eigen kopie van de ontvanger. Aan het gedownloade bestand verandert niets. De badge-afbeelding op zijn laptop ziet er identiek uit. Wat verandert is de uitkomst van de verificatie: iedereen die doorklikt of de credential programmatisch controleert, krijgt het antwoord «ingetrokken». Als je de ontvanger hebt gewaarschuwd, heeft hij ook een e-mail met uitleg waarom.

Op LinkedIn. Een credential die aan een LinkedIn-profiel is toegevoegd, is een link met metadata die terugwijst naar je verificatiepagina. LinkedIn controleert niet namens jou op intrekkingen, dus de vermelding kan op het profiel blijven staan, maar wie de link volgt komt op de pagina met de intrekking. Nog een reden om de melding te versturen en de ontvanger te vragen de vermelding te verwijderen.

Informeer je eigen systemen: webhooks

Intrekken is binnen je organisatie zelden het einde van het verhaal. De cursist moet misschien de toegang tot een community kwijtraken, een werkgeversrecord moet worden bijgewerkt of een CRM-tag moet verdwijnen. Badges Ninja verstuurt een credential.revoked-webhookevent wanneer een credential wordt ingetrokken, met de award-URL en de reden:

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

Abonneer je erop en je downstreamsystemen blijven synchroon zonder dat iemand eraan hoeft te denken ze bij te werken. De installatiedetails staan in de webhookdocumentatie, en het bredere eventmodel behandelen we in webhooks instellen voor badge-events.

Een eenvoudig intrekkingsbeleid dat je vandaag kunt overnemen

Tools zijn het makkelijke deel. Het moeilijkere deel is vooraf bepalen wanneer je intrekt en wie dat mag. Een kort schriftelijk beleid voorkomt later discussie. Een werkbaar sjabloon:

  1. Gronden voor intrekking. Som ze op: per ongeluk uitgegeven, verkregen via wangedrag, vereiste niet langer vervuld (bijvoorbeeld een lidmaatschap dat is verlopen) of programma ingetrokken.
  2. Wie beslist. Noem een rol, geen persoon. Beperk het recht om in te trekken tot die rol.
  3. Kennisgeving. Vermeld dat ontvangers per e-mail worden geïnformeerd, met de reden, tenzij de credential nooit is afgeleverd.
  4. Bezwaar. Geef ontvangers een manier om de beslissing aan te vechten en zeg hoe lang je erover doet om te reageren. Slaagt een bezwaar, geef dan een nieuwe credential uit in plaats van de intrekking ongedaan te maken te proberen, zodat de geschiedenis schoon blijft.
  5. Registratie. Houd intern bij wie wat heeft ingetrokken en waarom, los van de neutrale openbare reden.

Publiceer het beleid op dezelfde pagina waar je de credential beschrijft, zodat deelnemers de regels kennen voordat ze zich aanmelden.

Veelgemaakte fouten

  • Verwijderen terwijl je wilde intrekken. Verwijderen is definitief, kan niet ongedaan worden gemaakt en laat de openbare pagina verdwijnen. Gebruik het voor echte vergissingen bij credentials die niemand heeft gezien.
  • Privégegevens in de reden zetten. Die is openbaar op de assertion.
  • Verwachten dat opgeslagen kopieën veranderen. Intrekken leeft bij het verificatie-endpoint. Vraag ontvangers de credential uit profielen en portfolio’s te verwijderen.
  • Intrekken in plaats van laten verlopen. Gebruik een vervaldatum voor credentials met een beperkte looptijd.
  • Uitgaan van een terugbetaling. Ingetrokken credentials tellen nog steeds mee voor het quotum van je abonnement.
  • Downstreamsystemen vergeten. Koppel de webhook zodat toegang en records de status van de credential volgen.

Veelgestelde vragen

Kan ik een intrekking ongedaan maken? Niet via de interface. Heb je per ongeluk ingetrokken, geef dan een nieuwe credential uit aan de ontvanger. De ingetrokken blijft bestaan als onderdeel van de audittrail.

Hoeft de ontvanger iets te doen? Nee. Als je ervoor koos hem te waarschuwen, krijgt hij een e-mail. Anders gebeurt de wijziging geruisloos op de verificatiepagina.

Werkt intrekken ook voor credentials die nooit zijn verstuurd? Ja, al kun je bij een niet-verstuurde credential met een simpele fout beter bewerken vóór verzenden, of verwijderen als niemand hem heeft gezien.

Is er een limiet aan hoeveel ik kan intrekken? Bulk intrekken draait als hervatbare achtergrondtaak, dus grote batches worden in één bewerking afgehandeld in plaats van één voor één.

Zien werkgevers dat een credential is ingetrokken? Iedereen die de credential verifieert via de openbare URL of assertion ziet de ingetrokken status en de reden, als je die hebt opgegeven.

Conclusie

Een Open Badge intrekken is een kleine handeling met echte gevolgen voor vertrouwen. Doe het via het dashboard bij één credential, gebruik bulk intrekken voor een cohort en grijp naar de API of webhooks wanneer een ander systeem de beslissing neemt. Houd redenen neutraal, waarschuw wie het moet weten en onthoud dat intrekken verandert wat verificateurs zien, niet de bestanden die al bij ontvangers liggen.

Klaar om je eerste verifieerbare credential uit te geven? Begin gratis op badges.ninja — visuele designer, openbare verificatiepagina, pdf-certificaat, Open Badge v2.0-output. Geen creditcard nodig.

Nacho Coll

Over de auteur

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.

Terug naar blog

Gerelateerde artikelen