Udstedelse af Open Badges via Badges Ninja REST API: Quickstart

De fleste legitimationsprogrammer får aldrig brug for en API. Hvis du driver et kursus med nogle hundrede dimittender om året, klarer dashboardet det hele: du designer et badge i det visuelle designværktøj, uploader en CSV, og hver modtager får en verificeringsside og et PDF-certifikat. Hvis det er din situation, så start med sådan udsteder du Open Badges fra en CSV, og kom tilbage senere.

API’en kommer til sin ret, når legitimationer skal udstedes af et andet system: din læringsplatform markerer et kursus som gennemført, dit tilmeldingsværktøj lukker en begivenhed, dit HR-system registrerer et afsluttet compliance-modul. I de tilfælde vil ingen eksportere et regneark hver uge. Ét enkelt HTTP-kald i det øjeblik, noget er gennemført, er enklere, og modtageren får sit badge, mens præstationen stadig er frisk.

Denne quickstart gennemgår hele forløbet i fire kald: hent en nøgle, opret en udsteder, opret et badge, tildel det. Derefter ser vi på, hvordan du giver modtageren verificeringslinket, og hvordan du kontrollerer resultatet. Alle anmodningsformer nedenfor stammer fra de udrullede handlers, så du kan kopiere dem og køre dem.

Det skal du bruge, før du starter

• En gratis konto på badges.ninja. Free-planen er rigeligt til denne tutorial: den indeholder 2 udstedere, 5 badges, 2 pladser og 1 API-nøgle.
• Én API-nøgle, oprettet fra dashboardet.
• En PNG eller JPG til badgets billede, eller et badge, du har designet i det visuelle designværktøj.

Basis-URL’en til alt er https://api.badges.ninja.

Trin 1: Opret en API-nøgle

Log ind, åbn API Keys i sidemenuen, og klik på Create API Key. Giv den et navn, der fortæller, hvor den skal bruges, f.eks. “LMS integration”, så du kan kende nøglerne fra hinanden, når du senere roterer dem.

Nøglen vises præcis én gang. Kopiér den med det samme ind i din secrets manager eller en miljøvariabel. Nøgler ser ud som bws_ efterfulgt af 32 hex-tegn, og du sender dem i headeren X-Api-Key ved hver anmodning. Hvis du tilbagekalder en nøgle fra samme skærmbillede, træder det i kraft med det samme.

Et par vaner, der sparer dig for besvær senere:

• Læg aldrig nøglen i frontend-kode eller et offentligt repository. Kald API’en fra en server, en serverless-funktion eller et automatiseringsværktøj.
• Brug én nøgle pr. integration. Hvis én lækker, tilbagekalder du kun én integration i stedet for dem alle.
• Dashboardet accepterer også din indloggede session (en Cognito JWT sendt som Authorization: Bearer), men til scripts og integrationer er API-nøglen det rette værktøj.

Alle eksemplerne nedenfor læser nøglen fra en miljøvariabel ved navn BADGES_API_KEY.

Trin 2: Opret en udsteder

En udsteder er den organisation, der står bag badgen. Den vises på hver verificeringsside og i Open Badge v2.0-dataene, så brug det navn, folk faktisk kender.

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Academy","url":"https://acme.example.com","email":"badges@acme.example.com"}'

De obligatoriske felter er name (mindst 3 tegn), url (en gyldig http- eller https-adresse) og email. Valgfrie felter er logo (et base64-kodet billede) og linkedinOrganizationId, som aktiverer knappen Add to LinkedIn Profile på dine offentlige legitimationssider.

Svaret indeholder udstederens identifikator:

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Behold værdien præcis, som den blev returneret. Den bruges som input til næste trin.

Verificering af udsteder

Badges kan kun oprettes under en verificeret udsteder. Verificeringen fungerer sådan:

• Hvis udstederens e-mail matcher e-mailen på din konto, bliver udstederen verificeret automatisk. Det er den hurtigste vej til en første test.
• Hvis e-mailen er en anden, sendes en verificeringsmail med en kode til den adresse. Du bekræfter koden i dashboardet (eller via udsteder-API’en), før du opretter badges.

Til denne tutorial skal du derfor bruge den samme e-mail, som du oprettede kontoen med.

Trin 3: Opret et badge

Et badge er den genanvendelige skabelon: navn, beskrivelse, kriterier og billede. Hver tildeling, du udsteder senere, peger tilbage på det.

Anmodningen er almindelig JSON. Billedet sendes som en base64-streng, så der er ingen multipart-upload at kæmpe med. Et data-URL-præfiks som data:image/png;base64, accepteres og fjernes.

JavaScript (Node 18 eller nyere):

import { readFileSync } from "node:fs";
const API_KEY = process.env.BADGES_API_KEY;
const image = readFileSync("./badge.png").toString("base64");
const res = await fetch("https://api.badges.ninja/badges", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "JavaScript Fundamentals",
    description: "Demonstrates proficiency in core JavaScript concepts",
    criteria: "Completed the JavaScript Fundamentals course with a score of 80% or higher",
    image,
    issuerId: "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  }),
});
const { badgeId } = await res.json();
console.log(badgeId);

Python:

import base64, os, requests
API_KEY = os.environ["BADGES_API_KEY"]
with open("badge.png", "rb") as f:
    image = base64.b64encode(f.read()).decode()
res = requests.post(
    "https://api.badges.ninja/badges",
    headers={"X-Api-Key": API_KEY},
    json={
        "name": "JavaScript Fundamentals",
        "description": "Demonstrates proficiency in core JavaScript concepts",
        "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
        "image": image,
        "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    },
)
badge_id = res.json()["badgeId"]
print(badge_id)

Alle fem felter (name, description, criteria, image, issuerId) er obligatoriske. To valgfrie er værd at kende: shareText, standardteksten modtagerne ser, når de deler på sociale netværk (den understøtter pladsholderne {{badge_name}}, {{issuer_name}} og {{award_url}}), og designJson, som gemmer et dokument fra det visuelle designværktøj, så badgen senere kan redigeres lag for lag.

Et vellykket kald returnerer HTTP 200 med { "badgeId": "<id>" }. Billedet gemmes permanent, og badgen er nu en Open Badge v2.0 BadgeClass, som enhver kan hente.

Skal du overhovedet oprette badges i kode?

Som regel ikke. Badgedesign er en kreativ opgave, og det visuelle designværktøj (80+ skabeloner, former, ikoner, 11 skrifttyper og egne uploads) er et langt bedre sted at gøre det end et script. Et almindeligt mønster er at designe hvert badge én gang i dashboardet og så lade din integration udelukkende udstede tildelinger mod det. Du kan liste dine badges med GET /badges og kopiere id på det, du vil bruge.

Opret badges via API’en, når du genererer dem programmatisk, f.eks. ét pr. kursus i et katalog med hundredvis, eller når du fylder et testmiljø med data.

Trin 4: Tildel badgen

Det er det kald, din integration kommer til at foretage tusindvis af gange. Send badgen, modtageren og datoen.

curl:

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"badgeId":"<badge-id>","recipient":{"name":"Jane Smith","email":"jane@example.com"},"issuedOn":"2026-09-28"}'

JavaScript:

const res = await fetch("https://api.badges.ninja/awards", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    badgeId,
    recipient: { name: "Jane Smith", email: "jane@example.com" },
    issuedOn: Date.now(),
  }),
});
const { awardId } = await res.json();

Python:

import time, requests
res = requests.post(
    "https://api.badges.ninja/awards",
    headers={"X-Api-Key": API_KEY},
    json={
        "badgeId": badge_id,
        "recipient": {"name": "Jane Smith", "email": "jane@example.com"},
        "issuedOn": int(time.time() * 1000),
    },
)
award_id = res.json()["awardId"]

De regler, folk oftest snubler over:

• recipient er et indlejret objekt med name og email. Flade felter som recipientEmail afvises.
• recipient.name skal være mindst 5 tegn.
• issuedOn er obligatorisk. Send epoch-millisekunder eller en ISO-datostreng som 2026-09-28.
• expires er valgfri og accepterer de samme formater.

Et vellykket kald giver HTTP 200 med en body, der indeholder awardId. Modtagerens e-mail gemmes som en SHA-256-hash i Open Badge-dataene, så den offentlige JSON aldrig afslører den.

Trin 5: Find verificeringssiden og Open Badge-JSON’en

Tildelingssvaret giver dig en identifikator, ikke et færdigt link. Identifikatoren slutter med en GUID, og de offentlige sider bygges ud fra den GUID:

• Menneskelig læsbar verificeringsside: https://badges.ninja/awards/<awardId>
• Open Badge v2.0 JSON-LD: https://api.badges.ninja/certify-badge/award/<awardId>

Hvis din awardId kommer tilbage som en komplet URL, skal du bruge det sidste stisegment som GUID.

Begge er offentlige. Alle med linket kan verificere legitimationen uden at oprette en konto, og det er pointen: en arbejdsgiver eller en optagelsesansvarlig skal kunne kontrollere et badge på ti sekunder.

Hent JSON’en for at se, hvad omverdenen ser:

curl https://api.badges.ninja/certify-badge/award/<awardId>

Du får en Open Badge v2.0 Assertion: det badge, den refererer til, den hashede modtageridentitet, udstedelsesdatoen og en verificeringsblok, der peger tilbage på den hostede assertion. Fordi det er standard Open Badges-data, kan ethvert værktøj, der forstår formatet, læse det. Den portabilitet er grunden til at vælge Open Badges frem for en proprietær PDF; Open Badges vs PDF certificates går dybere ind i afvejningen.

Sådan modtager modtagerne legitimationen

At oprette en tildeling er noget andet end at fortælle modtageren om den. Modtagerne kan åbne deres legitimationer via modtagerportalen på badges.ninja/me, som bruger login med magic link uden adgangskode, og de kan udgive en offentlig profil på badges.ninja/u/<handle>. Fra verificeringssiden kan de tilføje badgen til LinkedIn, downloade PDF-certifikatet eller dele linket.

Send til de første par tests en tildeling til dig selv med din egen e-mailadresse, og gå modtagerens oplevelse igennem. Det er den hurtigste måde at opdage ting som en badgebeskrivelse, der lyder akavet.

Fejlhåndtering, der ikke gør ondt

API’en bruger almindelige HTTP-statuskoder. Dem, du kommer til at møde:

To praktiske tips. For det første: behandl 400 som et dataproblem, og log svarets body, da den navngiver det felt, der fejler. For det andet: gør din integration idempotent på din side. Gem awardId ved siden af gennemførelsesposten i din egen database, og tjek efter den, før du kalder API’en igen. På den måde udsteder en gentaget webhook eller et genkørt job aldrig den samme person to legitimationer.

Sådan sætter du det sammen i en rigtig integration

En typisk opsætning ser sådan ud:

1. Design badges i dashboardet, ét pr. kursus eller milepæl, og noter hvert badges ID.
2. Gem en mapping i dit system fra kursus til badge-ID.
3. Når en kursist gennemfører et kursus, kalder din server POST /awards med vedkommendes navn, e-mail og gennemførelsesdatoen.
4. Gem den returnerede awardId på gennemførelsesposten.
5. Vis verificeringslinket i dit eget produkt, så kursisten ser det uden at forlade det.

Hvis du hellere vil undgå at skrive kode, virker det samme kald fra ethvert automatiseringsværktøj, der kan sende en HTTP-anmodning med en JSON-body og en brugerdefineret header. Peg det på https://api.badges.ninja/awards, og map felterne fra din formular eller dit regneark til badgeId, recipient.name, recipient.email og issuedOn.

Planer og grænser, det er værd at kende

API’en er tilgængelig på alle planer; du betaler ikke ekstra for at låse op for den. Free-planen ($0) dækker 2 udstedere, 5 badges, 2 pladser, 1 API-nøgle og 1.200 legitimationer om året. Starter koster $9 om måneden og Pro $29 om måneden, med højere grænser. Se prissiden for de aktuelle tal, før du dimensionerer en udrulning. Hvis du sammenligner, hvad andre platforme tager for API-adgang, stiller Credly alternative omkostningerne op side om side.

Hvor du kan gå hen herfra

• Den fulde endpoint-reference findes i API-dokumentationen, som er tilgængelig på 40 sprog.
• Om godkendelse og håndtering af nøgler kan du læse i godkendelsesguiden.
• Om fejlkoder i detaljer kan du læse i fejlreferencen.
• Når ét kald ad gangen ikke længere slår til, kan du bruge masse-tildelinger i dashboardet: upload en CSV, og sæt kørslen på pause eller genoptag den, hvis du får brug for det.

Den første vellykkede tildeling er den svære. Derefter handler det bare om at koble det samme kald på de steder, hvor præstationer allerede bliver registreret.

Klar til at udstede din første verificerbare legitimation? Kom i gang gratis på badges.ninja — visuelt designværktøj, offentlig verificeringsside, PDF-certifikat, Open Badge v2.0-output. Intet kreditkort påkrævet.