Émettre des Open Badges via l’API REST de Badges Ninja : guide de démarrage rapide

La plupart des programmes de certification n’ont jamais besoin d’une API. Si vous animez une formation avec quelques centaines de diplômés par an, le tableau de bord fait tout : vous concevez un badge dans le concepteur visuel, vous importez un CSV, et chaque destinataire reçoit une page de vérification et un certificat PDF. Si c’est votre cas, commencez par émettre des Open Badges à partir d’un CSV et revenez plus tard.

L’API devient utile quand les certifications doivent être émises par un autre système : votre plateforme d’apprentissage marque un cours comme terminé, votre outil d’inscription clôture un événement, votre SIRH enregistre un module de conformité achevé. Dans ces cas, personne n’a envie d’exporter un tableur à la fin de chaque semaine. Un seul appel HTTP au moment de l’achèvement est plus simple, et le destinataire reçoit son badge alors que sa réussite est encore toute fraîche.

Ce guide parcourt tout le chemin en quatre appels : obtenir une clé, créer un émetteur, créer un badge, l’attribuer. Nous verrons ensuite comment transmettre le lien de vérification au destinataire et contrôler le résultat. Chaque forme de requête ci-dessous provient des handlers déployés : vous pouvez la copier-coller et l’exécuter.

Ce qu’il vous faut avant de commencer

• Un compte gratuit sur badges.ninja. Le plan Free suffit pour ce tutoriel : il comprend 2 émetteurs, 5 badges, 2 sièges et 1 clé d’API.
• Une clé d’API, créée depuis le tableau de bord.
• Un PNG ou un JPG pour l’image du badge, ou un badge conçu dans le concepteur visuel.

L’URL de base pour tout est https://api.badges.ninja.

Étape 1 : créer une clé d’API

Connectez-vous, ouvrez API Keys dans la barre latérale, puis cliquez sur Create API Key. Donnez-lui un nom qui indique où elle sera utilisée, par exemple « LMS integration », afin de pouvoir distinguer vos clés lorsque vous les ferez tourner plus tard.

La clé n’est affichée qu’une seule fois. Copiez-la immédiatement dans votre gestionnaire de secrets ou dans une variable d’environnement. Les clés ont la forme bws_ suivi de 32 caractères hexadécimaux, et vous les envoyez dans un en-tête X-Api-Key à chaque requête. La révocation d’une clé depuis ce même écran prend effet immédiatement.

Quelques bonnes habitudes qui évitent des ennuis :

• Ne mettez jamais la clé dans du code front-end ni dans un dépôt public. Appelez l’API depuis un serveur, une fonction serverless ou un outil d’automatisation.
• Utilisez une clé par intégration. Si l’une fuit, vous révoquez une seule intégration au lieu de toutes.
• Le tableau de bord accepte aussi votre session connectée (un JWT Cognito envoyé en Authorization: Bearer), mais pour les scripts et les intégrations, la clé d’API est le bon outil.

Tous les exemples ci-dessous lisent la clé dans une variable d’environnement nommée BADGES_API_KEY.

Étape 2 : créer un émetteur

Un émetteur est l’organisation qui se porte garante du badge. Il apparaît sur chaque page de vérification et dans les données Open Badge v2.0 : utilisez donc le nom que les gens connaissent réellement.

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

Les champs obligatoires sont name (au moins 3 caractères), url (une adresse http ou https valide) et email. Les champs facultatifs sont logo (une image encodée en base64) et linkedinOrganizationId, qui active le bouton Ajouter au profil LinkedIn sur vos pages de certifications publiques.

La réponse contient l’identifiant de l’émetteur :

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

Conservez cette valeur exactement telle qu’elle est renvoyée. C’est l’entrée de l’étape suivante.

Vérification de l’émetteur

Les badges ne peuvent être créés que sous un émetteur vérifié. La vérification fonctionne ainsi :

• Si l’e-mail de l’émetteur correspond à celui de votre compte, l’émetteur est vérifié automatiquement. C’est le chemin le plus rapide pour un premier test.
• Si l’e-mail est différent, un e-mail de vérification contenant un code est envoyé à cette adresse. Vous confirmez le code dans le tableau de bord (ou via l’API des émetteurs) avant de créer des badges.

Pour ce tutoriel, utilisez donc la même adresse e-mail que lors de votre inscription.

Étape 3 : créer un badge

Un badge est le modèle réutilisable : nom, description, critères et image. Chaque attribution que vous émettrez plus tard y renvoie.

La requête est du JSON ordinaire. L’image est transmise sous forme de chaîne base64 : pas d’envoi multipart avec lequel se battre. Un préfixe d’URL de données tel que data:image/png;base64, est accepté et retiré.

JavaScript (Node 18 ou version ultérieure) :

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)

Les cinq champs (name, description, criteria, image, issuerId) sont tous obligatoires. Deux champs facultatifs méritent d’être connus : shareText, le texte par défaut que les destinataires voient lorsqu’ils partagent sur les réseaux sociaux (il prend en charge les marqueurs {{badge_name}}, {{issuer_name}} et {{award_url}}), et designJson, qui stocke un document du concepteur visuel afin de pouvoir modifier le badge calque par calque par la suite.

En cas de succès, vous obtenez un HTTP 200 avec { "badgeId": "<id>" }. L’image est stockée de façon permanente, et le badge est désormais une BadgeClass Open Badge v2.0 que n’importe qui peut récupérer.

Faut-il vraiment créer des badges dans le code ?

En général, non. La conception d’un badge est une tâche créative, et le concepteur visuel (plus de 80 modèles, formes, icônes, 11 polices et imports personnalisés) y est bien mieux adapté qu’un script. Un schéma courant consiste à concevoir chaque badge une seule fois dans le tableau de bord, puis à ne faire émettre à votre intégration que des attributions. Vous pouvez lister vos badges avec GET /badges et copier l’id de celui que vous voulez.

Créez des badges via l’API lorsque vous les générez par programmation, par exemple un par cours dans un catalogue de centaines de formations, ou lorsque vous alimentez un environnement de test.

Étape 4 : attribuer le badge

C’est l’appel que votre intégration fera des milliers de fois. Envoyez le badge, le destinataire et la date.

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

Les règles qui font trébucher :

• recipient est un objet imbriqué avec name et email. Les champs à plat comme recipientEmail sont rejetés.
• recipient.name doit comporter au moins 5 caractères.
• issuedOn est obligatoire. Envoyez des millisecondes epoch ou une date ISO comme 2026-09-28.
• expires est facultatif et accepte les mêmes formats.

Un succès renvoie un HTTP 200 avec un corps contenant l’awardId. L’e-mail du destinataire est stocké sous forme de hachage SHA-256 dans les données Open Badge, de sorte que le JSON public ne l’expose jamais.

Étape 5 : trouver la page de vérification et le JSON Open Badge

La réponse de l’attribution vous donne un identifiant, pas un lien prêt à l’emploi. L’identifiant se termine par un GUID, et les pages publiques sont construites à partir de ce GUID :

• Page de vérification lisible par un humain : https://badges.ninja/awards/<awardId>
• JSON-LD Open Badge v2.0 : https://api.badges.ninja/certify-badge/award/<awardId>

Si votre awardId revient sous la forme d’une URL complète, utilisez le dernier segment du chemin comme GUID.

Les deux sont publics. Toute personne disposant du lien peut vérifier la certification sans créer de compte, et c’est tout l’intérêt : un employeur ou un responsable des admissions doit pouvoir contrôler un badge en dix secondes.

Récupérez le JSON pour voir ce que voit le monde entier :

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

Vous obtenez une Assertion Open Badge v2.0 : le badge référencé, l’identité hachée du destinataire, la date d’émission et un bloc de vérification renvoyant à l’assertion hébergée. Comme il s’agit de données Open Badges standard, tout outil qui comprend le format peut les lire. Cette portabilité est la raison de choisir Open Badges plutôt qu’un PDF propriétaire ; Open Badges ou certificats PDF approfondit ce compromis.

Comment les destinataires reçoivent leur certification

Créer une attribution est distinct du fait d’en informer le destinataire. Les destinataires peuvent ouvrir leurs certifications via le portail destinataire sur badges.ninja/me, qui utilise une connexion par lien magique sans mot de passe, et ils peuvent publier un profil public sur badges.ninja/u/<handle>. Depuis la page de vérification, ils peuvent ajouter le badge à LinkedIn, télécharger le certificat PDF ou partager le lien.

Pour les premiers tests, envoyez-vous une attribution avec votre propre adresse e-mail et parcourez l’expérience du destinataire. C’est le moyen le plus rapide de repérer des détails, comme une description de badge à la lecture maladroite.

Une gestion des erreurs qui ne fait pas mal

L’API utilise des codes d’état HTTP ordinaires. Voici ceux que vous rencontrerez :

Deux conseils pratiques. Premièrement, traitez le 400 comme un problème de données et journalisez le corps de la réponse, car il nomme le champ fautif. Deuxièmement, rendez votre intégration idempotente de votre côté : stockez l’awardId à côté de l’enregistrement d’achèvement dans votre propre base de données, et vérifiez sa présence avant de rappeler l’API. Ainsi, un webhook rejoué ou une tâche relancée n’émettra jamais deux certifications à la même personne.

Assembler le tout dans une vraie intégration

Un câblage typique ressemble à ceci :

1. Concevez les badges dans le tableau de bord, un par cours ou par étape, et notez l’ID de chaque badge.
2. Stockez dans votre système une correspondance entre chaque cours et son ID de badge.
3. Quand un apprenant termine un cours, votre serveur appelle POST /awards avec son nom, son e-mail et la date d’achèvement.
4. Enregistrez l’awardId renvoyé avec l’enregistrement d’achèvement.
5. Affichez le lien de vérification dans votre propre produit, pour que l’apprenant le voie sans le quitter.

Si vous préférez ne pas écrire de code, le même appel fonctionne depuis n’importe quel outil d’automatisation capable d’envoyer une requête HTTP avec un corps JSON et un en-tête personnalisé. Pointez-le vers https://api.badges.ninja/awards et faites correspondre les champs de votre formulaire ou de votre tableur à badgeId, recipient.name, recipient.email et issuedOn.

Plans et limites à connaître

L’API est disponible sur tous les plans ; vous ne payez rien de plus pour la débloquer. Le plan Free ($0) couvre 2 émetteurs, 5 badges, 2 sièges, 1 clé d’API et 1 200 certifications par an. Starter coûte $9 par mois et Pro $29 par mois, avec des limites plus élevées. Consultez la page des tarifs pour connaître les chiffres actuels avant de dimensionner un déploiement. Si vous comparez les tarifs d’accès à l’API pratiqués par d’autres plateformes, Alternative à Credly présente les coûts côte à côte.

Pour aller plus loin

• La référence complète des endpoints se trouve dans la documentation de l’API, disponible en 40 langues.
• Pour les détails sur l’authentification et la gestion des clés, consultez le guide d’authentification.
• Pour les codes d’erreur en détail, consultez la référence des erreurs.
• Quand l’appel unitaire ne suffit plus, utilisez les attributions en masse dans le tableau de bord : importez un CSV, et mettez l’exécution en pause ou reprenez-la si nécessaire.

La première attribution réussie est la partie difficile. Ensuite, il suffit de brancher le même appel aux endroits où les réussites sont déjà enregistrées.

Prêt à émettre votre première certification vérifiable ? Commencez gratuitement sur badges.ninja — concepteur visuel, page de vérification publique, certificat PDF, sortie Open Badge v2.0. Aucune carte bancaire requise.