Utfärda Open Badges via Badges Ninjas REST API: snabbstart

De flesta meritprogram behöver aldrig ett API. Om du driver en kurs med några hundra examinerade per år gör instrumentpanelen allt: du designar ett digitalt märke i den visuella designern, laddar upp en CSV, och varje mottagare får en verifieringssida och ett PDF-certifikat. Om det är din situation, börja med hur du utfärdar Open Badges från en CSV och kom tillbaka senare.

API:et gör nytta när meriter ska utfärdas av ett annat system: din lärplattform markerar en kurs som avklarad, ditt anmälningsverktyg stänger ett evenemang, ditt HR-system registrerar en genomförd utbildning. I de fallen vill ingen exportera ett kalkylblad i slutet av varje vecka. Ett enda HTTP-anrop i samma stund som kursen är klar är enklare, och mottagaren får sitt märke medan prestationen fortfarande är färsk.

Den här snabbstarten går igenom hela vägen i fyra anrop: skaffa en nyckel, skapa en utfärdare, skapa ett märke, tilldela det. Sedan tittar vi på hur du ger verifieringslänken till mottagaren och kontrollerar resultatet. Varje anropsformat nedan kommer från de driftsatta hanterarna, så du kan klistra in det och köra.

Det här behöver du innan du börjar

• Ett gratis konto på badges.ninja. Free-planen räcker för den här guiden: den inkluderar 2 utfärdare, 5 märken, 2 platser och 1 API-nyckel.
• En API-nyckel, skapad från instrumentpanelen.
• En PNG eller JPG till märkets bild, eller ett märke du designat i den visuella designern.

Bas-URL:en för allt är https://api.badges.ninja.

Steg 1: Skapa en API-nyckel

Logga in, öppna API Keys i sidofältet och klicka på Create API Key. Ge den ett namn som visar var den ska användas, till exempel ”LMS integration”, så att du kan skilja nycklarna åt när du roterar dem senare.

Nyckeln visas exakt en gång. Kopiera den direkt till din hemlighetshanterare eller en miljövariabel. Nycklarna ser ut som bws_ följt av 32 hexadecimala tecken, och du skickar dem i rubriken X-Api-Key vid varje anrop. Om du återkallar en nyckel från samma sida får det effekt direkt.

Några vanor som sparar besvär senare:

• Lägg aldrig nyckeln i frontend-kod eller ett publikt repo. Anropa API:et från en server, en serverlös funktion eller ett automatiseringsverktyg.
• Använd en nyckel per integration. Om en läcker återkallar du en integration i stället för alla.
• Instrumentpanelen godtar också din inloggade session (en Cognito JWT som skickas som Authorization: Bearer), men för skript och integrationer är API-nyckeln rätt verktyg.

Alla exempel nedan läser nyckeln från en miljövariabel som heter BADGES_API_KEY.

Steg 2: Skapa en utfärdare

En utfärdare är organisationen som står bakom märket. Den visas på varje verifieringssida och i Open Badge v2.0-datan, så använd det namn folk faktiskt känner till.

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 obligatoriska fälten är name (minst 3 tecken), url (en giltig http- eller https-adress) och email. Valfria fält är logo (en base64-kodad bild) och linkedinOrganizationId, som aktiverar knappen Add to LinkedIn Profile på dina publika meritsidor.

Svaret innehåller utfärdarens identifierare:

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

Behåll värdet exakt som det returnerades. Det är indata till nästa steg.

Verifiering av utfärdare

Märken kan bara skapas under en verifierad utfärdare. Verifieringen fungerar så här:

• Om utfärdarens e-postadress matchar e-postadressen på ditt konto verifieras utfärdaren automatiskt. Det är den snabbaste vägen för ett första test.
• Om e-postadressen är en annan skickas ett verifieringsmejl med en kod till den adressen. Du bekräftar koden i instrumentpanelen (eller via utfärdar-API:et) innan du skapar märken.

I den här guiden använder du alltså samma e-postadress som du registrerade dig med.

Steg 3: Skapa ett märke

Ett märke är den återanvändbara mallen: namn, beskrivning, kriterier och bild. Varje tilldelning du utfärdar senare pekar tillbaka på den.

Anropet är vanlig JSON. Bilden skickas som en base64-sträng, så du slipper kämpa med multipart-uppladdning. Ett data-URL-prefix som data:image/png;base64, accepteras och tas bort.

JavaScript (Node 18 eller senare):

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)

Alla fem fälten (name, description, criteria, image, issuerId) är obligatoriska. Två valfria är värda att känna till: shareText, standardtexten som mottagarna ser när de delar på sociala nätverk (den stöder platshållarna {{badge_name}}, {{issuer_name}} och {{award_url}}), och designJson, som lagrar ett dokument från den visuella designern så att märket kan redigeras lager för lager senare.

Ett lyckat anrop ger HTTP 200 med { "badgeId": "<id>" }. Bilden lagras permanent, och märket är nu en Open Badge v2.0 BadgeClass som vem som helst kan hämta.

Bör du över huvud taget skapa märken i kod?

Oftast inte. Märkesdesign är en kreativ uppgift, och den visuella designern (80+ mallar, former, ikoner, 11 typsnitt och egna uppladdningar) är en mycket bättre plats för den än ett skript. Ett vanligt mönster är att designa varje märke en gång i instrumentpanelen och låta din integration enbart utfärda tilldelningar mot det. Du kan lista dina märken med GET /badges och kopiera id för det du vill ha.

Skapa märken via API:et när du genererar dem programmatiskt, till exempel ett per kurs i en katalog med hundratals, eller när du fyller en testmiljö med data.

Steg 4: Tilldela märket

Det här är anropet som din integration kommer att göra tusentals gånger. Skicka märket, mottagaren och datumet.

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

Reglerna som folk snubblar på:

• recipient är ett nästlat objekt med name och email. Platta fält som recipientEmail avvisas.
• recipient.name måste vara minst 5 tecken.
• issuedOn är obligatoriskt. Skicka epok-millisekunder eller en ISO-datumsträng som 2026-09-28.
• expires är valfritt och tar samma format.

Ett lyckat anrop ger HTTP 200 med en svarskropp som innehåller awardId. Mottagarens e-postadress lagras som en SHA-256-hash i Open Badge-datan, så den publika JSON-filen avslöjar den aldrig.

Steg 5: Hitta verifieringssidan och Open Badge-JSON

Svaret från tilldelningen ger dig en identifierare, inte en färdig länk. Identifieraren slutar på en GUID, och de publika sidorna byggs utifrån den GUID:en:

• Läsbar verifieringssida: https://badges.ninja/awards/<awardId>
• Open Badge v2.0 JSON-LD: https://api.badges.ninja/certify-badge/award/<awardId>

Om din awardId kommer tillbaka som en fullständig URL, använd sista sökvägssegmentet som GUID.

Båda är publika. Den som har länken kan verifiera meriten utan att skapa ett konto, och det är poängen: en arbetsgivare eller antagningshandläggare ska kunna kontrollera ett märke på tio sekunder.

Hämta JSON-filen för att se vad omvärlden ser:

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

Du får en Open Badge v2.0 Assertion: märket den refererar till, mottagarens hashade identitet, utfärdandedatumet och ett verifieringsblock som pekar tillbaka på den hostade assertionen. Eftersom det är standardiserad Open Badges-data kan alla verktyg som förstår formatet läsa den. Den portabiliteten är skälet att välja Open Badges framför en proprietär PDF; Open Badges vs PDF certificates går djupare in på avvägningen.

Så får mottagarna meriten

Att skapa en tilldelning är något annat än att tala om det för mottagaren. Mottagarna kan öppna sina meriter via mottagarportalen på badges.ninja/me, som använder inloggning med magisk länk utan lösenord, och de kan publicera en offentlig profil på badges.ninja/u/<handle>. Från verifieringssidan kan de lägga till märket på LinkedIn, ladda ner PDF-certifikatet eller dela länken.

För de första testerna: skicka en tilldelning till din egen e-postadress och gå igenom mottagarens upplevelse. Det är det snabbaste sättet att upptäcka saker som en märkesbeskrivning som låter krystad.

Felhantering som inte gör ont

API:et använder vanliga HTTP-statuskoder. Dessa kommer du att stöta på:

Två praktiska tips. För det första: behandla 400 som ett dataproblem och logga svarskroppen, eftersom den namnger det fält som felar. För det andra: gör din integration idempotent på din sida: lagra awardId bredvid avklarningsposten i din egen databas och kontrollera den innan du anropar API:et igen. Då utfärdar en omskickad webhook eller ett omkört jobb aldrig två meriter till samma person.

Så sätter du ihop det i en riktig integration

En typisk koppling ser ut så här:

1. Designa märken i instrumentpanelen, ett per kurs eller milstolpe, och notera varje märkes ID.
2. Lagra en koppling i ditt system från kurs till märkes-ID.
3. När en deltagare slutför en kurs anropar din server POST /awards med namn, e-postadress och slutdatum.
4. Spara den returnerade awardId mot avklarningsposten.
5. Visa verifieringslänken i din egen produkt, så att deltagaren ser den utan att lämna den.

Vill du hellre slippa skriva kod fungerar samma anrop från vilket automatiseringsverktyg som helst som kan skicka en HTTP-förfrågan med JSON-kropp och en egen rubrik. Peka det mot https://api.badges.ninja/awards och koppla fälten i ditt formulär eller kalkylblad till badgeId, recipient.name, recipient.email och issuedOn.

Planer och gränser värda att känna till

API:et ingår i alla planer; du betalar inget extra för att låsa upp det. Free-planen ($0) omfattar 2 utfärdare, 5 märken, 2 platser, 1 API-nyckel och 1,200 meriter per år. Starter kostar $9 per månad och Pro $29 per månad, med högre gränser. Kolla prissidan för aktuella siffror innan du dimensionerar en utrullning. Om du jämför vad andra plattformar tar betalt för API-åtkomst ställer Credly alternative kostnaderna sida vid sida.

Vart du går härnäst

• Den fullständiga endpoint-referensen finns i API-dokumentationen, som finns på 40 språk.
• För detaljer om autentisering och nyckelhantering, se autentiseringsguiden.
• För felkoder på djupet, se felreferensen.
• När du växer ur ett anrop i taget kan du använda massutdelning i instrumentpanelen: ladda upp en CSV och pausa eller återuppta körningen vid behov.

Den första lyckade tilldelningen är den svåra delen. Efter det handlar allt om att koppla in samma anrop på de ställen där prestationer redan registreras.

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