Utstede Open Badges via Badges Ninja REST API: Quickstart

De fleste programmer for digitale kvalifikasjoner trenger aldri et API. Hvis du driver et kurs med noen hundre kandidater i året, klarer dashbordet alt: du designer et merke i det visuelle designverktøyet, laster opp en CSV, og hver mottaker får en verifiseringsside og et PDF-sertifikat. Hvis det er din situasjon, start med hvordan du utsteder Open Badges fra en CSV, og kom tilbake senere.

API-et kommer til sin rett når kvalifikasjoner skal utstedes av et annet system: læringsplattformen din markerer et kurs som fullført, påmeldingsverktøyet ditt avslutter et arrangement, HR-systemet ditt registrerer en ferdig compliance-modul. I de tilfellene vil ingen eksportere et regneark på slutten av hver uke. Ett enkelt HTTP-kall i det øyeblikket noe er fullført er enklere, og mottakeren får merket sitt mens prestasjonen fortsatt er fersk.

Denne quickstarten går gjennom hele løpet i fire kall: hent en nøkkel, opprett en utsteder, opprett et merke, tildel det. Deretter ser vi på hvordan du gir verifiseringslenken til mottakeren og kontrollerer resultatet. Alle forespørselsformene nedenfor kommer fra de utrullede handlerne, så du kan lime dem inn og kjøre dem.

Dette trenger du før du starter

• En gratis konto på badges.ninja. Free-planen er nok for denne veiledningen: den inkluderer 2 utstedere, 5 merker, 2 seter og 1 API-nøkkel.
• Én API-nøkkel, opprettet fra dashbordet.
• En PNG eller JPG til merkebildet, eller et merke du har designet i det visuelle designverktøyet.

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

Trinn 1: Opprett en API-nøkkel

Logg inn, åpne API Keys i sidemenyen, og klikk på Create API Key. Gi den et navn som sier hvor den skal brukes, for eksempel “LMS integration”, slik at du kan skille nøklene fra hverandre når du roterer dem senere.

Nøkkelen vises nøyaktig én gang. Kopier den rett inn i secrets manageren din eller en miljøvariabel. Nøkler ser ut som bws_ etterfulgt av 32 hex-tegn, og du sender dem i en X-Api-Key-header ved hver forespørsel. Hvis du tilbakekaller en nøkkel fra samme skjermbilde, trer det i kraft umiddelbart.

Noen vaner som sparer deg for bry senere:

• Legg aldri nøkkelen i frontend-kode eller et offentlig repository. Kall API-et fra en server, en serverless-funksjon eller et automatiseringsverktøy.
• Bruk én nøkkel per integrasjon. Hvis én lekker, tilbakekaller du én integrasjon i stedet for alle.
• Dashbordet godtar også den innloggede sesjonen din (en Cognito JWT sendt som Authorization: Bearer), men for skript og integrasjoner er API-nøkkelen det riktige verktøyet.

Alle eksemplene nedenfor leser nøkkelen fra en miljøvariabel som heter BADGES_API_KEY.

Trinn 2: Opprett en utsteder

En utsteder er organisasjonen som står bak merket. Den vises på hver verifiseringsside og i Open Badge v2.0-dataene, så bruk navnet folk faktisk kjenner.

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

Obligatoriske felt er name (minst 3 tegn), url (en gyldig http- eller https-adresse) og email. Valgfrie felt er logo (et base64-kodet bilde) og linkedinOrganizationId, som slår på knappen Add to LinkedIn Profile på de offentlige kvalifikasjonssidene dine.

Svaret inneholder utstederens identifikator:

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

Behold verdien nøyaktig slik den ble returnert. Den brukes som input i neste trinn.

Verifisering av utsteder

Merker kan bare opprettes under en verifisert utsteder. Verifiseringen fungerer slik:

• Hvis utstederens e-post samsvarer med e-posten på kontoen din, blir utstederen verifisert automatisk. Dette er den raskeste veien for en første test.
• Hvis e-posten er en annen, sendes en verifiseringse-post med en kode til den adressen. Du bekrefter koden i dashbordet (eller via utsteder-API-et) før du oppretter merker.

I denne veiledningen bør du derfor bruke den samme e-posten som du registrerte deg med.

Trinn 3: Opprett et merke

Et merke er den gjenbrukbare malen: navn, beskrivelse, kriterier og bilde. Hver tildeling du utsteder senere peker tilbake til det.

Forespørselen er vanlig JSON. Bildet sendes som en base64-streng, så du slipper multipart-opplasting. Et data-URL-prefiks som data:image/png;base64, godtas 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 feltene (name, description, criteria, image, issuerId) er obligatoriske. To valgfrie er verdt å kjenne til: shareText, standardteksten mottakerne ser når de deler på sosiale nettverk (den støtter plassholderne {{badge_name}}, {{issuer_name}} og {{award_url}}), og designJson, som lagrer et dokument fra det visuelle designverktøyet slik at merket kan redigeres lag for lag senere.

Et vellykket kall gir HTTP 200 med { "badgeId": "<id>" }. Bildet lagres permanent, og merket er nå en Open Badge v2.0 BadgeClass som hvem som helst kan hente.

Bør du i det hele tatt opprette merker i kode?

Vanligvis ikke. Merkedesign er en kreativ oppgave, og det visuelle designverktøyet (80+ maler, former, ikoner, 11 skrifttyper og egne opplastinger) er et mye bedre sted for det enn et skript. Et vanlig mønster er å designe hvert merke én gang i dashbordet, og la integrasjonen din bare utstede tildelinger mot det. Du kan liste merkene dine med GET /badges og kopiere id til det du vil bruke.

Opprett merker via API-et når du genererer dem programmatisk, for eksempel ett per kurs i en katalog med hundrevis, eller når du fyller et testmiljø med data.

Trinn 4: Tildel merket

Dette er kallet integrasjonen din kommer til å foreta tusenvis av ganger. Send merket, mottakeren 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"]

Reglene folk oftest snubler i:

• recipient er et nøstet objekt med name og email. Flate felt som recipientEmail blir avvist.
• recipient.name må være minst 5 tegn.
• issuedOn er obligatorisk. Send epoch-millisekunder eller en ISO-datostreng som 2026-09-28.
• expires er valgfri og tar de samme formatene.

Et vellykket kall gir HTTP 200 med en body som inneholder awardId. Mottakerens e-post lagres som en SHA-256-hash i Open Badge-dataene, så den offentlige JSON-en avslører den aldri.

Trinn 5: Finn verifiseringssiden og Open Badge-JSON-en

Tildelingssvaret gir deg en identifikator, ikke en ferdig lenke. Identifikatoren ender med en GUID, og de offentlige sidene bygges fra den GUID-en:

• Menneskelesbar verifiseringsside: https://badges.ninja/awards/<awardId>
• Open Badge v2.0 JSON-LD: https://api.badges.ninja/certify-badge/award/<awardId>

Hvis awardId kommer tilbake som en full URL, bruker du det siste stisegmentet som GUID.

Begge er offentlige. Alle med lenken kan verifisere kvalifikasjonen uten å opprette en konto, og det er poenget: en arbeidsgiver eller en opptaksansvarlig skal kunne sjekke et merke på ti sekunder.

Hent JSON-en for å se hva omverdenen ser:

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

Du får en Open Badge v2.0 Assertion: merket den refererer til, den hashede mottakeridentiteten, utstedelsesdatoen og en verifiseringsblokk som peker tilbake til den hostede assertionen. Fordi det er standard Open Badges-data, kan ethvert verktøy som forstår formatet lese det. Den portabiliteten er grunnen til å velge Open Badges fremfor en proprietær PDF; Open Badges vs PDF certificates går dypere inn på avveiningen.

Slik mottar mottakerne kvalifikasjonen

Å opprette en tildeling er noe annet enn å fortelle mottakeren om den. Mottakerne kan åpne kvalifikasjonene sine via mottakerportalen på badges.ninja/me, som bruker pålogging med magic link uten passord, og de kan publisere en offentlig profil på badges.ninja/u/<handle>. Fra verifiseringssiden kan de legge merket til LinkedIn, laste ned PDF-sertifikatet eller dele lenken.

For de første testene kan du sende en tildeling til deg selv med din egen e-postadresse og gå gjennom mottakerens opplevelse. Det er den raskeste måten å oppdage ting som en merkebeskrivelse som høres klønete ut.

Feilhåndtering som ikke gjør vondt

API-et bruker vanlige HTTP-statuskoder. Disse kommer du til å møte:

To praktiske tips. For det første: behandle 400 som et dataproblem og logg svarets body, siden den nevner feltet som feiler. For det andre: gjør integrasjonen din idempotent på din side. Lagre awardId ved siden av fullføringsposten i din egen database, og sjekk etter den før du kaller API-et på nytt. Da utsteder en gjentatt webhook eller en omkjørt jobb aldri to kvalifikasjoner til samme person.

Slik setter du det sammen i en ekte integrasjon

En typisk oppsett ser slik ut:

1. Design merker i dashbordet, ett per kurs eller milepæl, og noter hvert merkes ID.
2. Lagre en mapping i systemet ditt fra kurs til merke-ID.
3. Når en deltaker fullfører et kurs, kaller serveren din POST /awards med navn, e-post og fullføringsdato.
4. Lagre den returnerte awardId på fullføringsposten.
5. Vis verifiseringslenken i ditt eget produkt, slik at deltakeren ser den uten å forlate det.

Hvis du heller vil slippe å skrive kode, fungerer det samme kallet fra ethvert automatiseringsverktøy som kan sende en HTTP-forespørsel med en JSON-body og en egendefinert header. Pek det mot https://api.badges.ninja/awards, og map feltene fra skjemaet eller regnearket ditt til badgeId, recipient.name, recipient.email og issuedOn.

Planer og grenser det er verdt å kjenne til

API-et er tilgjengelig på alle planer; du betaler ikke ekstra for å låse det opp. Free-planen ($0) dekker 2 utstedere, 5 merker, 2 seter, 1 API-nøkkel og 1 200 kvalifikasjoner i året. Starter koster $9 per måned og Pro $29 per måned, med høyere grenser. Sjekk prissiden for gjeldende tall før du dimensjonerer en utrulling. Hvis du sammenligner hva andre plattformer tar for API-tilgang, setter Credly alternative kostnadene opp side om side.

Veien videre

• Den fullstendige endepunktreferansen finner du i API-dokumentasjonen, som er tilgjengelig på 40 språk.
• For detaljer om autentisering og nøkkelhåndtering, se autentiseringsguiden.
• For feilkoder i detalj, se feilreferansen.
• Når ett kall om gangen ikke lenger holder, bruk masse-tildelinger i dashbordet: last opp en CSV, og sett kjøringen på pause eller gjenoppta den ved behov.

Den første vellykkede tildelingen er den vanskelige. Etter det handler det bare om å koble det samme kallet til stedene der prestasjoner allerede blir registrert.

Klar til å utstede din første verifiserbare kvalifikasjon? Kom i gang gratis på badges.ninja — visuelt designverktøy, offentlig verifiseringsside, PDF-sertifikat, Open Badge v2.0-output. Ikke noe kredittkort nødvendig.