Så återkallar du ett Open Badge (och vad som händer med mottagarens kopia)

Återkallelse i Open Badges: hur det fungerar, vad som förändras för mottagaren och hur du hanterar „utfärdad av misstag”, „giltighetstiden har gått ut” och „regelbrott” på rätt sätt.

Nacho Coll Av Uppdaterad 10 min läsning
Återkallelse i Open Badges: hur det fungerar, vad som förändras för mottagaren och hur du hanterar „utfärdad av misstag”, „giltighetstiden har gått ut” och „regelbrott” på rätt sätt.

Förr eller senare måste varje program som utfärdar digitala meriter ta tillbaka en. Ett certifikat gick till fel person. En deltagare visade sig ha fuskat på slutprovet. Ett partneravtal tog slut, och märkena som sa „Certifierad partner” ska inte längre gälla. Att utfärda är den enkla delen; återkallelsen avgör om dina meriter faktiskt går att lita på.

Den här guiden förklarar hur återkallelse fungerar i Open Badges, vad mottagaren ser och inte ser efteråt, och hur du återkallar en enskild merit eller några hundra på https://badges.ninja, från instrumentpanelen eller via API:et.

Vad „återkalla” betyder i Open Badges

I specifikationen Open Badges v2.0 är varje utfärdat märke en assertion (påstående): ett litet JSON-LD-dokument på en offentlig adress som säger ”den här utfärdaren tilldelade det här märket till den här mottagaren på det här datumet”. Återkallelse är helt enkelt en ändring av det publicerade dokumentet. Assertionen får "revoked": true och, om du vill, en textsträng "revocationReason" som förklarar varför.

Den utformningen får en viktig konsekvens som överraskar många programansvariga:

  • Den publicerade assertionen är sanningskällan. Den som verifierar meriten genom att hämta assertionens URL eller öppna verifieringssidan ser det återkallade tillståndet direkt.
  • Kopior återkallas inte. Om mottagaren har laddat ner märkesbilden eller JSON-filen, eller fäst den i en portfölj, ändras inte den filen. Den innehåller fortfarande en länk tillbaka till din publicerade assertion, så en verifierare som följer länken ser att den är återkallad, men den som bara tittar på en sparad PNG gör det inte.

Återkallelse är alltså ett uttalande vid verifieringsslutpunkten, inte en radering. Tänk på det som att stämpla ”OGILTIG” på originalet i stället för att jaga rätt på varje fotokopia.

Vill du titta närmare på själva dokumentet går vår genomgång av Open Badge JSON-LD igenom varje fält.

Återkalla, utfärda på nytt eller radera: välj rätt åtgärd

Innan du klickar på något, bestäm vilken av de tre åtgärderna som passar situationen. De är inte utbytbara.

SituationBästa åtgärdVarför
Meriten utfärdades till fel person eller med ett stavfelRadera (om den aldrig skickats) eller Återkalla, och utfärda sedan på nyttRadering tar bort posten helt; återkallelse bevarar ett revisionsspår
Deltagaren bröt mot en regel eller meriten erhölls på olämpligt sättÅterkalla, med en orsakPosten förblir verifierbar som återkallad, vilket är precis vad du vill ha vid en tvist
Meriten har helt enkelt nått sitt slutdatumGör ingenting; ange ett utgångsdatum när du utfärdarUtgång är en normal del av livscykeln, inte en återkallelse
Programmet inställt, kohorten ogiltigförklaradMassåterkallelseEtt jobb, en orsak, tillämpad på alla
Uppgifterna var fel men meriten är i övrigt giltigRedigera före utskick, eller återkalla och utfärda på nytt efter utskickHåller mottagarens upplevelse ren

Två tumregler:

  1. Föredra återkallelse framför radering för allt som är på riktigt. En raderad merits offentliga sida ger felet ”hittades inte”. En återkallad går fortfarande att öppna och säger tydligt att den är återkallad, vilket är ett mycket bättre bevis om någon senare frågar vad som hände.
  2. Använd aldrig återkallelse som ersättning för utgång. Om en merit bara gäller i två år, ange ett utgångsdatum när du utfärdar den. Ett märke som tyst går ut är något annat än ett som drogs tillbaka, och din verifieringssida bör tala om vilket det är.

Återkalla från instrumentpanelen

För ett fåtal meriter är instrumentpanelen den snabbaste vägen och kräver ingen kod.

  1. Logga in och öppna Awards i sidomenyn.
  2. Hitta meriten. Listan visar mottagare, märkesnamn, utfärdandedatum och utgångsdatum, och du kan söka på mottagare.
  3. Klicka på raden (eller View) för att öppna meritens detaljfönster.
  4. Klicka på Revoke.
  5. I bekräftelsedialogen kan du ange en orsak och, om du vill, kryssa i Email the recipient that their credential was revoked.
  6. Bekräfta.

Award detail modal

Meriten ligger kvar i din lista med en röd Revoked-etikett bredvid mottagaren, så att du och ditt team alltid ser vad som har dragits tillbaka. Återkallelsen ger ingen återbetalning mot din plans kvot. Du utfärdade den, den räknades.

En anmärkning om orsaksfältet

Orsaken är valfri, men fyll i den. Den lagras tillsammans med meriten, visas som revocationReason i den offentliga Open Badges-assertionen och ingår i webhook-payloaden som dina system får. Eftersom den är offentlig på assertionen bör du skriva den som för en utomstående läsare. ”Utfärdad av misstag” eller ”Programmet inställt” går bra. ”Jane fuskade på fråga 14” gör det inte. Behåll personliga uppgifter i dina egna register och håll den offentliga orsaken neutral.

Ska du mejla mottagaren?

Oftast ja. En deltagare som får veta att meriten är död först när en arbetsgivare klickar på verifieringslänken har all rätt att vara missnöjd med dig. Aviseringen är valfri just för att vissa återkallelser (till exempel en massrensning av testutmärkelser) inte behöver störa någon. Vår rekommendation:

  • Mejla när återkallelsen berör en verklig person som fortfarande kan visa upp meriten.
  • Hoppa över mejlet när du städar interna testdata eller ogiltigförklarar meriter som aldrig skickats.

Återkalla många meriter på en gång

Program behöver sällan återkalla en enda merit; oftare gäller det en hel kohort. I Awards-listan:

  1. Markera kryssrutorna för de meriter du vill dra tillbaka.
  2. Klicka på Revoke selected i fältet för massåtgärder.
  3. Lägg till en orsak och bestäm om mottagarna ska aviseras, och bekräfta sedan.

Massåterkallelse körs som ett varaktigt bakgrundsjobb, så några hundra meriter får inte din webbläsarflik att time-outa. Meriter som redan är återkallade hoppas över i stället för att få hela partiet att misslyckas, och ett jobb som avbryts halvvägs kan återupptas. Samma mekanism driver massutfärdande från ett kalkylblad, vilket vi går igenom i hur du utfärdar Open Badges från en CSV.

Återkalla via API:et

Om ditt lärsystem eller din HR-plattform avgör vem som inte längre är certifierad kan du återkalla programmatiskt. Slutpunkten är POST /awards/{awardId}/revoke, autentiserad med en API-nyckel (X-Api-Key: bws_<32-hex>) eller en Cognito Bearer-token. Award-ID:t anges i sökvägen; reason och notify anges i JSON-kroppen och båda är valfria.

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

I 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

Och i 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

Några praktiska detaljer som är bra att känna till:

  • Den är idempotent. Att återkalla en merit som redan är återkallad ger samma lyckade svar och skickar ingen andra avisering. Det gör anropet säkert att använda från ett jobb som försöker igen.
  • Orsaker kortas av till 500 tecken.
  • notify är false som standard. Inget mejlas om du inte ber om det.
  • Massåterkallelse finns via bulk-slutpunkten med action: "revoke" och en lista med award-ID:n; den returnerar ett jobb-ID som du kan följa. Alla parametrar finns i API-referensen för awards.

Du behöver bara API:et när återkallelsen styrs av ett annat system. För ett enstaka fall går instrumentpanelen snabbare och har ett bekräftelsesteg som skyddar dig mot ett felskrivet ID.

Vad mottagaren och verifieraren ser

Efter återkallelsen ändras följande, och så här snabbt.

På den offentliga verifieringssidan. Sidan på https://badges.ninja/awards/<award-id> visar meriten som återkallad, och sidtiteln för delning i sociala medier får prefixet ”[Revoked]” så att en delad länk inte ser ut som en giltig merit i ett förhandsvisningskort.

I Open Badges v2.0-assertionen. JSON-filen på https://api.badges.ninja/certify-badge/award/<award-id> innehåller nu "revoked": true, plus "revocationReason" om du angav en. Återkallade assertioner cachas bara i ungefär 30 sekunder, medan aktiva cachas i fem minuter, så ändringen når verifierarna snabbt.

I Open Badges 3.0-meriten. Återkallelsen växlar också meritens bit i en W3C Bitstring Status List, vilket är hur plånböcker och verifierare för verifierbara meriter upptäcker den. Listan cachas kort, så räkna med spridning inom ungefär en minut. Om du väger de två versionerna mot varandra, se Open Badges v2 vs v3.

I mottagarens egen kopia. Ingenting ändras i filen de laddade ner. Märkesbilden på deras dator ser likadan ut. Det som ändras är resultatet av verifieringen: den som klickar sig vidare eller kontrollerar meriten programmatiskt får svaret att den är återkallad. Om du aviserade dem har de också fått ett mejl som förklarar varför.

På LinkedIn. En merit som lagts till i en LinkedIn-profil är en länk plus metadata som pekar tillbaka på din verifieringssida. LinkedIn kontrollerar inte återkallelse åt dig, så posten kan ligga kvar på profilen, men den som följer länken hamnar på den återkallade sidan. Det är ännu en anledning att skicka aviseringen och be mottagaren ta bort posten.

Berätta för dina egna system: webhooks

Återkallelse är sällan slutet på historien inom din organisation. Deltagaren kan behöva förlora åtkomst till en community, en arbetsgivarpost kan behöva uppdateras eller en CRM-tagg tas bort. Badges Ninja skickar ut en webhook-händelse credential.revoked när en merit återkallas, med award-URL:en och orsaken:

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

Prenumerera på den så hålls dina efterföljande system i takt utan att någon behöver komma ihåg att uppdatera dem. Installationsdetaljer finns i webhook-dokumentationen, och den bredare händelsemodellen tar vi upp i webhook-installation för märkeshändelser.

En enkel återkallelsepolicy du kan införa idag

Verktygen är den enkla halvan. Den svårare halvan är att i förväg bestämma när du ska återkalla och vem som får göra det. En kort skriftlig policy förebygger bråk senare. En användbar mall:

  1. Grunder för återkallelse. Lista dem: utfärdad av misstag, erhållen genom regelbrott, krav som inte längre uppfylls (till exempel ett medlemskap som löpt ut) eller program som dragits tillbaka.
  2. Vem som beslutar. Ange en roll, inte en person. Begränsa behörigheten att återkalla till den rollen.
  3. Avisering. Ange att mottagare meddelas via mejl, med orsaken, om inte meriten aldrig levererats.
  4. Överklagande. Ge mottagarna ett sätt att bestrida beslutet och säg hur lång tid du tar på dig att svara. Om ett överklagande går igenom, utfärda en ny merit i stället för att försöka ogöra återkallelsen, så förblir historiken ren.
  5. Dokumentation. För en intern anteckning om vem som återkallade vad och varför, skild från den neutrala offentliga orsaken.

Publicera policyn på samma sida där du beskriver meriten, så att den som får den känner till reglerna innan de anmäler sig.

Vanliga misstag att undvika

  • Radera när du menade återkalla. Radering är permanent, kan inte ångras och får den offentliga sidan att försvinna. Använd den för verkliga misstag på meriter som ingen har sett.
  • Privata uppgifter i orsaken. Den är offentlig på assertionen.
  • Att vänta sig att sparade kopior ändras. Återkallelsen finns vid verifieringsslutpunkten. Be mottagarna ta bort meriten från profiler och portföljer.
  • Återkalla i stället för att låta gå ut. Använd ett utgångsdatum för tidsbegränsade meriter.
  • Anta en återbetalning. Återkallade meriter räknas fortfarande mot din plans kvot.
  • Glömma efterföljande system. Koppla in webhooken så att åtkomst och register följer meritens status.

Vanliga frågor

Kan jag ångra en återkallelse? Inte via gränssnittet. Om du återkallade av misstag, utfärda en ny merit till mottagaren. Den återkallade finns kvar som en del av revisionsspåret.

Behöver mottagaren göra något? Nej. Om du valde att avisera dem får de ett mejl. Annars sker ändringen tyst på verifieringssidan.

Fungerar återkallelse för meriter som aldrig skickats? Ja, men för en oskickad merit med ett enkelt fel kanske du hellre redigerar den före utskick, eller raderar den om ingen har sett den.

Finns det en gräns för hur många jag kan återkalla? Massåterkallelse körs som ett återupptagbart bakgrundsjobb, så stora partier hanteras i en enda operation i stället för en i taget.

Kommer arbetsgivare att se att en merit har återkallats? Alla som verifierar den via dess offentliga URL eller assertion ser den återkallade statusen och orsaken, om du angav någon.

Slutsats

Att återkalla ett Open Badge är en liten åtgärd med verkliga konsekvenser för förtroendet. Gör det från instrumentpanelen när det gäller en enskild merit, använd massåterkallelse för en kohort och ta till API:et eller webhooks när ett annat system äger beslutet. Håll orsakerna neutrala, avisera dem som behöver veta och kom ihåg att återkallelse ändrar vad verifierare ser, inte de filer som redan ligger hos mottagarna.

Redo att utfärda din första verifierbara merit? Börja gratis på badges.ninja — visuell designer, offentlig verifieringssida, PDF-certifikat, Open Badge v2.0-utdata. Inget kreditkort krävs.

Nacho Coll

Om författaren

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.

Tillbaka till Bloggen

Relaterade artiklar