Open Badges über die Badges-Ninja-REST-API ausstellen: Quickstart

Die meisten Credential-Programme brauchen nie eine API. Wenn du einen Kurs mit ein paar hundert Absolvent:innen pro Jahr betreibst, erledigt das Dashboard alles: Du gestaltest ein Abzeichen im visuellen Designer, lädst eine CSV hoch, und jede:r Empfänger:in bekommt eine Verifizierungsseite und ein PDF-Zertifikat. Wenn das auf dich zutrifft, starte mit Open Badges aus einer CSV ausstellen und komm später wieder.

Die API lohnt sich, wenn Credentials von einem anderen System ausgestellt werden sollen: Deine Lernplattform markiert einen Kurs als abgeschlossen, dein Anmeldetool schließt eine Veranstaltung ab, dein HR-System erfasst ein beendetes Compliance-Modul. In solchen Fällen will niemand am Ende jeder Woche eine Tabelle exportieren. Ein einziger HTTP-Aufruf im Moment des Abschlusses ist einfacher, und die Empfänger:innen bekommen ihr Abzeichen, solange die Leistung noch frisch ist.

Dieser Quickstart führt in vier Aufrufen durch den ganzen Weg: Schlüssel holen, Aussteller anlegen, Abzeichen erstellen, vergeben. Danach schauen wir uns an, wie du den Verifizierungslink an die Empfänger:innen weitergibst und das Ergebnis prüfst. Jede Request-Form unten stammt aus den produktiven Handlern, du kannst sie also einfach kopieren und ausführen.

Was du vor dem Start brauchst

• Ein kostenloses Konto bei badges.ninja. Der Free-Plan reicht für dieses Tutorial: Er enthält 2 Aussteller, 5 Abzeichen, 2 Seats und 1 API-Schlüssel.
• Einen API-Schlüssel, erstellt im Dashboard.
• Ein PNG oder JPG für das Abzeichenbild oder ein Abzeichen, das du im visuellen Designer gestaltet hast.

Die Basis-URL für alles ist https://api.badges.ninja.

Schritt 1: Einen API-Schlüssel erstellen

Melde dich an, öffne API Keys in der Seitenleiste und klicke auf Create API Key. Gib ihm einen Namen, der verrät, wo er eingesetzt wird, etwa „LMS integration“, damit du die Schlüssel beim späteren Rotieren auseinanderhalten kannst.

Der Schlüssel wird genau einmal angezeigt. Kopiere ihn sofort in deinen Secrets-Manager oder eine Umgebungsvariable. Schlüssel sehen so aus: bws_ gefolgt von 32 Hex-Zeichen, und du sendest sie bei jeder Anfrage im Header X-Api-Key. Einen Schlüssel auf demselben Bildschirm zu widerrufen, wirkt sofort.

Ein paar Gewohnheiten, die dir später Ärger ersparen:

• Packe den Schlüssel niemals in Frontend-Code oder ein öffentliches Repository. Rufe die API von einem Server, einer Serverless-Funktion oder einem Automatisierungstool aus auf.
• Nutze einen Schlüssel pro Integration. Wenn einer leakt, widerrufst du eine Integration statt aller.
• Das Dashboard akzeptiert auch deine angemeldete Sitzung (ein Cognito-JWT, gesendet als Authorization: Bearer), aber für Skripte und Integrationen ist der API-Schlüssel das richtige Werkzeug.

Alle Beispiele unten lesen den Schlüssel aus einer Umgebungsvariable namens BADGES_API_KEY.

Schritt 2: Einen Aussteller anlegen

Ein Aussteller ist die Organisation, die hinter dem Abzeichen steht. Er erscheint auf jeder Verifizierungsseite und in den Open-Badge-v2.0-Daten, nimm also den Namen, den die Leute tatsächlich 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"}'

Pflichtfelder sind name (mindestens 3 Zeichen), url (eine gültige http- oder https-Adresse) und email. Optional sind logo (ein base64-kodiertes Bild) und linkedinOrganizationId, das den Button „Zum LinkedIn-Profil hinzufügen“ auf deinen öffentlichen Credential-Seiten aktiviert.

Die Antwort enthält die Aussteller-Kennung:

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

Behalte diesen Wert exakt so, wie er zurückkommt. Er ist die Eingabe für den nächsten Schritt.

Verifizierung des Ausstellers

Abzeichen können nur unter einem verifizierten Aussteller erstellt werden. So funktioniert die Verifizierung:

• Stimmt die E-Mail-Adresse des Ausstellers mit der E-Mail deines Kontos überein, wird der Aussteller automatisch verifiziert. Das ist der schnellste Weg für einen ersten Test.
• Ist die E-Mail-Adresse eine andere, geht eine Verifizierungs-E-Mail mit einem Code an diese Adresse. Du bestätigst den Code im Dashboard (oder über die Aussteller-API), bevor du Abzeichen erstellst.

Nimm für dieses Tutorial also dieselbe E-Mail-Adresse, mit der du dich registriert hast.

Schritt 3: Ein Abzeichen erstellen

Ein Abzeichen ist die wiederverwendbare Vorlage: Name, Beschreibung, Kriterien und Bild. Jede Vergabe, die du später ausstellst, verweist darauf zurück.

Die Anfrage ist schlichtes JSON. Das Bild wird als base64-String übergeben, du musst dich also nicht mit einem Multipart-Upload herumschlagen. Ein Data-URL-Präfix wie data:image/png;base64, wird akzeptiert und entfernt.

JavaScript (Node 18 oder neuer):

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 fünf Felder (name, description, criteria, image, issuerId) sind Pflicht. Zwei optionale Felder solltest du kennen: shareText, der Standardtext, den Empfänger:innen beim Teilen in sozialen Netzwerken sehen (er unterstützt die Platzhalter {{badge_name}}, {{issuer_name}} und {{award_url}}), und designJson, das ein Dokument des visuellen Designers speichert, damit das Abzeichen später Ebene für Ebene bearbeitet werden kann.

Bei Erfolg kommt HTTP 200 mit { "badgeId": "<id>" } zurück. Das Bild wird dauerhaft gespeichert, und das Abzeichen ist nun eine Open-Badge-v2.0-BadgeClass, die jede:r abrufen kann.

Sollte man Abzeichen überhaupt per Code erstellen?

Meistens nicht. Abzeichen-Design ist eine kreative Aufgabe, und der visuelle Designer (80+ Vorlagen, Formen, Icons, 11 Schriftarten und eigene Uploads) ist dafür ein viel besserer Ort als ein Skript. Ein gängiges Muster: Jedes Abzeichen einmal im Dashboard gestalten, und deine Integration stellt danach nur noch Vergaben dafür aus. Mit GET /badges listest du deine Abzeichen auf und kopierst die id des gewünschten.

Erstelle Abzeichen über die API, wenn du sie programmatisch erzeugst, zum Beispiel eines pro Kurs in einem Katalog mit Hunderten Einträgen, oder wenn du eine Testumgebung befüllst.

Schritt 4: Das Abzeichen vergeben

Das ist der Aufruf, den deine Integration tausendfach machen wird. Sende das Abzeichen, den Empfänger und das Datum.

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"]

Die Regeln, über die man gern stolpert:

• recipient ist ein verschachteltes Objekt mit name und email. Flache Felder wie recipientEmail werden abgelehnt.
• recipient.name muss mindestens 5 Zeichen lang sein.
• issuedOn ist Pflicht. Sende Epoch-Millisekunden oder einen ISO-Datumsstring wie 2026-09-28.
• expires ist optional und akzeptiert dieselben Formate.

Ein Erfolg ist HTTP 200 mit einem Body, der die awardId enthält. Die E-Mail-Adresse des Empfängers wird in den Open-Badge-Daten als SHA-256-Hash gespeichert, das öffentliche JSON legt sie also nie offen.

Schritt 5: Verifizierungsseite und Open-Badge-JSON finden

Die Antwort auf die Vergabe liefert dir eine Kennung, keinen fertigen Link. Die Kennung endet auf eine GUID, und aus dieser GUID werden die öffentlichen Seiten gebildet:

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

Kommt deine awardId als vollständige URL zurück, nimm das letzte Pfadsegment als GUID.

Beide sind öffentlich. Jede:r mit dem Link kann das Credential ohne Konto verifizieren, und genau das ist der Punkt: Ein Arbeitgeber oder eine Zulassungsstelle sollte ein Abzeichen in zehn Sekunden prüfen können.

Rufe das JSON ab, um zu sehen, was die Welt sieht:

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

Du erhältst eine Open-Badge-v2.0-Assertion: das referenzierte Abzeichen, die gehashte Empfängeridentität, das Ausstellungsdatum und einen Verifizierungsblock, der auf die gehostete Assertion zurückverweist. Da es sich um Standard-Open-Badges-Daten handelt, kann jedes Tool, das das Format versteht, sie lesen. Diese Portabilität ist der Grund, Open Badges einem proprietären PDF vorzuziehen; Open Badges vs. PDF-Zertifikate geht tiefer auf den Zielkonflikt ein.

Wie Empfänger:innen das Credential erhalten

Eine Vergabe zu erstellen ist etwas anderes, als den Empfänger darüber zu informieren. Empfänger:innen können ihre Credentials über das Empfängerportal unter badges.ninja/me öffnen, das Magic-Link-Anmeldung ohne Passwort nutzt, und sie können ein öffentliches Profil unter badges.ninja/u/<handle> veröffentlichen. Von der Verifizierungsseite aus können sie das Abzeichen zu LinkedIn hinzufügen, das PDF-Zertifikat herunterladen oder den Link teilen.

Schicke dir für die ersten Tests selbst eine Vergabe an deine eigene E-Mail-Adresse und geh die Empfängererfahrung durch. So fallen Dinge wie eine holprig formulierte Abzeichenbeschreibung am schnellsten auf.

Fehlerbehandlung, die nicht wehtut

Die API verwendet gewöhnliche HTTP-Statuscodes. Diese wirst du antreffen:

Zwei praktische Tipps. Erstens: Behandle 400 als Datenproblem und protokolliere den Response-Body, denn er nennt das fehlerhafte Feld. Zweitens: Mach deine Integration auf deiner Seite idempotent: Speichere die awardId neben dem Abschlusseintrag in deiner eigenen Datenbank und prüfe sie, bevor du die API erneut aufrufst. So stellt ein wiederholter Webhook oder ein erneuter Job nie derselben Person zwei Credentials aus.

Alles zusammen in einer echten Integration

Eine typische Verdrahtung sieht so aus:

1. Gestalte die Abzeichen im Dashboard, eines pro Kurs oder Meilenstein, und notiere dir jede Abzeichen-ID.
2. Hinterlege in deinem System eine Zuordnung von Kurs zu Abzeichen-ID.
3. Schließt ein:e Lernende:r einen Kurs ab, ruft dein Server POST /awards mit Name, E-Mail und Abschlussdatum auf.
4. Speichere die zurückgegebene awardId beim Abschlusseintrag.
5. Zeige den Verifizierungslink in deinem eigenen Produkt an, damit die lernende Person ihn sieht, ohne es zu verlassen.

Wenn du lieber keinen Code schreiben willst, funktioniert derselbe Aufruf in jedem Automatisierungstool, das eine HTTP-Anfrage mit JSON-Body und eigenem Header senden kann. Richte es auf https://api.badges.ninja/awards und ordne deine Formular- oder Tabellenfelder badgeId, recipient.name, recipient.email und issuedOn zu.

Pläne und Limits, die du kennen solltest

Die API ist in jedem Plan verfügbar; für die Freischaltung zahlst du nichts extra. Der Free-Plan ($0) umfasst 2 Aussteller, 5 Abzeichen, 2 Seats, 1 API-Schlüssel und 1.200 Credentials pro Jahr. Starter kostet $9 pro Monat und Pro $29 pro Monat, mit höheren Limits. Prüfe die Preisseite auf die aktuellen Zahlen, bevor du einen Rollout dimensionierst. Wenn du vergleichst, was andere Plattformen für API-Zugang verlangen, legt Credly-Alternative die Kosten nebeneinander dar.

Wie es weitergeht

• Die vollständige Endpunkt-Referenz findest du in der API-Dokumentation, die in 40 Sprachen verfügbar ist.
• Details zur Authentifizierung und zum Umgang mit Schlüsseln stehen in den Authentifizierungsleitfaden.
• Fehlercodes im Detail findest du in die Fehlerreferenz.
• Wenn du aus dem Ein-Aufruf-pro-Mal-Modus herauswächst, nutze Bulk-Vergaben im Dashboard: CSV hochladen und den Lauf bei Bedarf pausieren oder fortsetzen.

Die erste erfolgreiche Vergabe ist der schwierige Teil. Danach geht es nur noch darum, denselben Aufruf dort einzubauen, wo Leistungen ohnehin erfasst werden.

Bereit, dein erstes verifizierbares Credential auszustellen? Starte kostenlos bei badges.ninja – visueller Designer, öffentliche Verifizierungsseite, PDF-Zertifikat, Open-Badge-v2.0-Ausgabe. Keine Kreditkarte nötig.