API Émetteurs

Gérez les émetteurs de badges — les organisations ou les particuliers qui émettent des badges.

Tous les points de terminaison nécessitent une authentification via l'en-tête X-Api-Key. Voir Authentification.

Créer un émetteur

Créez un nouvel émetteur de badges.

POST /issuers

Paramètres

Paramètre	Type	Obligatoire	Description
name	string	Oui	Nom de l'organisation (3 caractères minimum)
url	string	Oui	Site web de l'organisation (doit être une URL HTTP/HTTPS valide)
email	string	Oui	E-mail de contact de l'émetteur
logo	string	Non	Image encodée en Base64 (PNG ou JPG)
linkedinOrganizationId	string	Non	Identifiant numérique de la page entreprise LinkedIn. Lorsqu'il est défini, chaque page publique d'attestation de cet émetteur affiche un bouton Add to LinkedIn Profile.

Exemple

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com"
    }
  }'

Réponse

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

Notes

• Compte dans la limite d'émetteurs de votre plan (Free : 2, Starter : 5, Pro : 10). Aucune déduction de quota.
• Si l'e-mail de l'émetteur correspond à l'e-mail de votre compte, l'émetteur est vérifié automatiquement.
• Si l'e-mail est différent, un e-mail de vérification est envoyé à l'adresse de l'émetteur.
• Après avoir configuré un émetteur, utilisez l'API Attestations pour commencer à émettre des attestations sous cet émetteur.

---

Lister les émetteurs

Récupérez tous les émetteurs que vous avez créés.

GET /issuers

Exemple

curl -X GET https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here"

Réponse

{
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com",
      "verified": true,
      "timestamp": 1736937000000
    }
  ]
}

timestamp est une époque Unix en millisecondes. Lorsqu'il existe plus d'émetteurs que ce qui tient dans une page, un lastEvaluatedKey est également renvoyé pour la pagination.

---

Vérifier un émetteur

Vérifiez un émetteur avec le code de vérification envoyé à son adresse e-mail.

POST /issuers/{issuerId}/verify

Paramètres

Paramètre	Type	Obligatoire	Description
issuerId	string	Oui	L'identifiant de l'émetteur (paramètre de chemin)
code	string	Oui	Le code de vérification reçu par e-mail

Exemple

curl -X POST https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "ABC123"
    }
  }'

Réponse

Une simple chaîne :

"issuer has been verified"

---

Supprimer un émetteur

Supprimez un émetteur. Aucun badge ne doit lui être lié.

DELETE /issuers/{issuerId}

Exemple

curl -X DELETE https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: bws_your_api_key_here"

Réponse

Une simple chaîne :

"issuer has been deleted"

Erreurs

• 400 — des badges sont encore liés à l'émetteur : issuer has {n} badge(s) linked — delete the badges first. La suppression est bloquée uniquement par les badges liés — les attestations ne l'empêchent pas.
• 404 — émetteur introuvable

---

Mettre à jour un émetteur

Mettez à jour les champs d'un émetteur. Seuls les émetteurs non vérifiés peuvent être modifiés — une fois l'émetteur vérifié, ce point de terminaison renvoie 400 verified issuers cannot be edited afin de préserver la stabilité des attestations. La modification d'un émetteur régénère son code de vérification : si l'email correspond à l'e-mail de votre compte, l'émetteur est automatiquement revérifié ; sinon, un nouvel e-mail de vérification est envoyé à cette adresse.

PUT /issuers/{issuerId}

Paramètres

Paramètre	Type	Obligatoire	Description
issuerId	string	Oui	L'identifiant de l'émetteur (paramètre de chemin)
name	string	Non	Nouveau nom
url	string	Non	Nouvelle URL
email	string	Non	Nouvel e-mail (envoie un nouvel e-mail de vérification, sauf s'il correspond à l'e-mail de votre compte)
logo	string	Non	Nouveau logo encodé en Base64
linkedinOrganizationId	string	Non	Nouvel identifiant d'organisation LinkedIn (ou chaîne vide pour l'effacer)

Réponse

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "updated": true
}

Erreurs

• 400 — verified issuers cannot be edited (l'émetteur est déjà vérifié)
• 400 — not authorized (l'émetteur appartient à un autre compte)
• 404 — émetteur introuvable