Open Badges uitgeven via de Badges Ninja REST API: quickstart

De meeste certificeringsprogramma’s hebben nooit een API nodig. Als je een cursus geeft met een paar honderd afgestudeerden per jaar, doet het dashboard alles: je ontwerpt een badge in de visuele designer, uploadt een CSV en elke ontvanger krijgt een verificatiepagina en een pdf-certificaat. Is dat jouw situatie, begin dan met hoe je Open Badges uitgeeft vanuit een CSV en kom later terug.

De API verdient zijn plek wanneer een ander systeem de credentials moet uitgeven: je leerplatform markeert een cursus als afgerond, je registratietool sluit een evenement af, je HR-systeem legt een afgeronde compliancemodule vast. Dan wil niemand aan het eind van elke week een spreadsheet exporteren. Eén HTTP-call op het moment van afronding is simpeler, en de ontvanger krijgt zijn badge terwijl de prestatie nog vers is.

Deze quickstart doorloopt het hele traject in vier calls: een sleutel ophalen, een uitgever aanmaken, een badge aanmaken en die toekennen. Daarna kijken we hoe je de verificatielink bij de ontvanger krijgt en het resultaat controleert. Elke request-vorm hieronder komt uit de gedeployde handlers, dus je kunt hem kopiëren en uitvoeren.

Wat je nodig hebt voordat je begint

• Een gratis account op badges.ninja. Het Free-plan is genoeg voor deze tutorial: het bevat 2 uitgevers, 5 badges, 2 seats en 1 API-sleutel.
• Eén API-sleutel, aangemaakt vanuit het dashboard.
• Een PNG of JPG voor de badgeafbeelding, of een badge die je in de visuele designer hebt ontworpen.

De basis-URL voor alles is https://api.badges.ninja.

Stap 1: maak een API-sleutel aan

Log in, open API Keys in de zijbalk en klik op Create API Key. Geef de sleutel een naam die zegt waar hij gaat wonen, zoals “LMS integration”, zodat je sleutels uit elkaar kunt houden als je ze later roteert.

De sleutel wordt precies één keer getoond. Kopieer hem meteen naar je secretsmanager of een omgevingsvariabele. Sleutels zien eruit als bws_ gevolgd door 32 hexadecimale tekens, en je stuurt ze bij elk verzoek mee in een X-Api-Key-header. Een sleutel intrekken via hetzelfde scherm werkt direct.

Een paar gewoontes die je later gedoe besparen:

• Zet de sleutel nooit in front-endcode of een openbare repository. Roep de API aan vanaf een server, een serverless functie of een automatiseringstool.
• Gebruik één sleutel per integratie. Lekt er een, dan trek je één integratie in in plaats van alle.
• Het dashboard accepteert ook je ingelogde sessie (een Cognito JWT, verstuurd als Authorization: Bearer), maar voor scripts en integraties is de API-sleutel het juiste gereedschap.

Alle voorbeelden hieronder lezen de sleutel uit een omgevingsvariabele met de naam BADGES_API_KEY.

Stap 2: maak een uitgever aan

Een uitgever is de organisatie die achter de badge staat. Die staat op elke verificatiepagina en in de Open Badge v2.0-data, dus gebruik de naam die mensen echt kennen.

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 verplichte velden zijn name (minstens 3 tekens), url (een geldig http- of https-adres) en email. Optionele velden zijn logo (een base64-gecodeerde afbeelding) en linkedinOrganizationId, waarmee de knop Add to LinkedIn Profile op je openbare credentialpagina’s wordt ingeschakeld.

Het antwoord bevat de identifier van de uitgever:

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

Bewaar die waarde precies zoals je hem terugkrijgt. Hij is de input voor de volgende stap.

Verificatie van de uitgever

Badges kunnen alleen worden aangemaakt onder een geverifieerde uitgever. Verificatie werkt zo:

• Komt het e-mailadres van de uitgever overeen met het e-mailadres van je account, dan wordt de uitgever automatisch geverifieerd. Dit is de snelste weg voor een eerste test.
• Is het e-mailadres anders, dan gaat er een verificatiemail met een code naar dat adres. Je bevestigt de code in het dashboard (of via de uitgevers-API) voordat je badges aanmaakt.

Gebruik voor deze tutorial dus hetzelfde e-mailadres als waarmee je je hebt aangemeld.

Stap 3: maak een badge aan

Een badge is de herbruikbare sjabloon: naam, beschrijving, criteria en afbeelding. Elke toekenning die je later uitgeeft, verwijst ernaar terug.

Het verzoek is gewone JSON. De afbeelding gaat mee als base64-string, dus je hoeft niet te worstelen met een multipart-upload. Een data-URL-prefix zoals data:image/png;base64, wordt geaccepteerd en eraf gehaald.

JavaScript (Node 18 of hoger):

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 vijf de velden (name, description, criteria, image, issuerId) zijn verplicht. Twee optionele velden zijn het onthouden waard: shareText, de standaardtekst die ontvangers zien als ze op sociale netwerken delen (die ondersteunt de placeholders {{badge_name}}, {{issuer_name}} en {{award_url}}), en designJson, waarin een document van de visuele designer wordt opgeslagen zodat de badge later laag voor laag kan worden bewerkt.

Bij succes krijg je HTTP 200 met { "badgeId": "<id>" }. De afbeelding wordt permanent opgeslagen en de badge is nu een Open Badge v2.0 BadgeClass die iedereen kan ophalen.

Moet je badges eigenlijk in code aanmaken?

Meestal niet. Een badge ontwerpen is een creatieve taak, en de visuele designer (80+ sjablonen, vormen, iconen, 11 lettertypen en eigen uploads) is daar een stuk beter voor geschikt dan een script. Een veelgebruikt patroon is om elke badge één keer in het dashboard te ontwerpen en je integratie alleen toekenningen daarop te laten uitgeven. Je kunt je badges oplijsten met GET /badges en de id kopiëren van degene die je wilt.

Maak badges via de API aan als je ze programmatisch genereert, bijvoorbeeld één per cursus in een catalogus van honderden, of als je een testomgeving vult.

Stap 4: ken de badge toe

Dit is de call die je integratie duizenden keren gaat doen. Stuur de badge, de ontvanger en de datum mee.

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 regels waar mensen over struikelen:

• recipient is een geneste object met name en email. Platte velden zoals recipientEmail worden geweigerd.
• recipient.name moet minstens 5 tekens lang zijn.
• issuedOn is verplicht. Stuur epoch-milliseconden of een ISO-datumstring zoals 2026-09-28.
• expires is optioneel en accepteert dezelfde formaten.

Succes is HTTP 200 met een body die de awardId bevat. Het e-mailadres van de ontvanger wordt als SHA-256-hash opgeslagen in de Open Badge-data, dus de openbare JSON onthult het nooit.

Stap 5: vind de verificatiepagina en de Open Badge JSON

Het antwoord van de toekenning geeft je een identifier, geen kant-en-klare link. De identifier eindigt op een GUID, en de openbare pagina’s worden van die GUID opgebouwd:

• Voor mensen leesbare verificatiepagina: https://badges.ninja/awards/<awardId>
• Open Badge v2.0 JSON-LD: https://api.badges.ninja/certify-badge/award/<awardId>

Komt je awardId terug als volledige URL, gebruik dan het laatste padsegment als GUID.

Beide zijn openbaar. Iedereen met de link kan de credential verifiëren zonder account, en dat is precies de bedoeling: een werkgever of toelatingsmedewerker moet een badge in tien seconden kunnen controleren.

Haal de JSON op om te zien wat de buitenwereld ziet:

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

Je krijgt een Open Badge v2.0 Assertion: de badge waarnaar verwezen wordt, de gehashte identiteit van de ontvanger, de uitgiftedatum en een verificatieblok dat terugwijst naar de gehoste assertion. Omdat het standaard Open Badges-data is, kan elke tool die het formaat begrijpt het lezen. Die overdraagbaarheid is de reden om voor Open Badges te kiezen in plaats van een eigen pdf; Open Badges vs PDF certificates gaat dieper in op de afweging.

Hoe ontvangers de credential krijgen

Een toekenning aanmaken is iets anders dan de ontvanger erover informeren. Ontvangers kunnen hun credentials openen via het ontvangersportaal op badges.ninja/me, dat inlogt met een magic link zonder wachtwoord, en ze kunnen een openbaar profiel publiceren op badges.ninja/u/<handle>. Vanaf de verificatiepagina kunnen ze de badge aan LinkedIn toevoegen, het pdf-certificaat downloaden of de link delen.

Stuur jezelf voor de eerste tests een toekenning met je eigen e-mailadres en doorloop de ervaring van de ontvanger. Zo merk je het snelst dingen op, zoals een badgebeschrijving die onhandig leest.

Foutafhandeling die geen pijn doet

De API gebruikt gewone HTTP-statuscodes. Dit zijn de codes die je tegenkomt:

Twee praktische tips. Eerst: behandel een 400 als een dataprobleem en log de response-body, want die noemt het veld dat misgaat. Daarnaast: maak je integratie aan jouw kant idempotent. Sla de awardId op naast het afrondingsrecord in je eigen database en controleer die voordat je de API opnieuw aanroept. Zo geeft een opnieuw afgevuurde webhook of een herstarte job nooit twee credentials aan dezelfde persoon.

Alles samenbrengen in een echte integratie

Een typische opzet ziet er zo uit:

1. Ontwerp badges in het dashboard, één per cursus of mijlpaal, en noteer elke badge-ID.
2. Sla in je systeem een koppeling op van cursus naar badge-ID.
3. Wanneer een leerling een cursus afrondt, roept je server POST /awards aan met naam, e-mailadres en afrondingsdatum.
4. Bewaar de teruggekregen awardId bij het afrondingsrecord.
5. Toon de verificatielink in je eigen product, zodat de leerling die ziet zonder weg te gaan.

Wil je liever geen code schrijven, dan werkt dezelfde call vanuit elke automatiseringstool die een HTTP-verzoek met een JSON-body en een eigen header kan versturen. Richt hem op https://api.badges.ninja/awards en koppel je formulier- of spreadsheetvelden aan badgeId, recipient.name, recipient.email en issuedOn.

Plannen en limieten om te kennen

De API is beschikbaar op elk plan; je betaalt niets extra om hem te ontgrendelen. Het Free-plan ($0) dekt 2 uitgevers, 5 badges, 2 seats, 1 API-sleutel en 1.200 credentials per jaar. Starter kost $9 per maand en Pro $29 per maand, met hogere limieten. Bekijk de prijspagina voor de actuele cijfers voordat je een uitrol dimensioneert. Vergelijk je wat andere platforms rekenen voor API-toegang, dan zet Credly alternative de kosten naast elkaar.

Waar nu heen

• De volledige endpointreferentie staat in de API-documentatie, die in 40 talen beschikbaar is.
• Voor details over authenticatie en sleutelbeheer, zie de authenticatiegids.
• Voor foutcodes in detail, zie de foutenreferentie.
• Als één call tegelijk niet meer volstaat, gebruik dan bulktoekenningen in het dashboard: upload een CSV en pauzeer of hervat de run als dat nodig is.

De eerste geslaagde toekenning is het moeilijkste deel. Daarna is de rest gewoon dezelfde call inpluggen op de plekken waar prestaties al worden vastgelegd.

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.