Aussteller-API

Verwalte Aussteller von Abzeichen — die Organisationen oder Einzelpersonen, die Abzeichen ausstellen.

Alle Endpunkte erfordern Authentifizierung über den X-Api-Key-Header. Siehe Authentifizierung.

Aussteller erstellen

Erstellt einen neuen Aussteller für Abzeichen.

POST /issuers

Parameter

Parameter	Typ	Erforderlich	Beschreibung
name	string	Ja	Name der Organisation (mindestens 3 Zeichen)
url	string	Ja	Website der Organisation (muss eine gültige HTTP/HTTPS-URL sein)
email	string	Ja	Kontakt-E-Mail des Ausstellers
logo	string	Nein	Base64-kodiertes Bild (PNG oder JPG)
linkedinOrganizationId	string	Nein	Numerische ID der LinkedIn-Unternehmensseite. Wenn gesetzt, zeigt jede öffentliche Nachweisseite dieses Ausstellers einen Button Add to LinkedIn Profile.

Beispiel

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

Antwort

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

Hinweise

• Zählt auf das Aussteller-Limit deines Plans (Free: 2, Starter: 5, Pro: 10). Es wird kein Kontingent abgezogen.
• Stimmt die E-Mail des Ausstellers mit deiner Konto-E-Mail überein, wird der Aussteller automatisch verifiziert.
• Weicht die E-Mail ab, wird eine Verifizierungs-E-Mail an die Aussteller-E-Mail gesendet.
• Nach der Konfiguration eines Ausstellers kannst du mit der Nachweise-API beginnen, Nachweise unter diesem Aussteller auszustellen.

---

Aussteller auflisten

Ruft alle von dir erstellten Aussteller ab.

GET /issuers

Beispiel

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

Antwort

{
  "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 ist eine Unix-Epoche in Millisekunden. Gibt es mehr Aussteller, als auf eine Seite passen, wird zusätzlich ein lastEvaluatedKey für die Paginierung zurückgegeben.

---

Aussteller verifizieren

Verifiziert einen Aussteller mit dem Verifizierungscode, der an seine E-Mail gesendet wurde.

POST /issuers/{issuerId}/verify

Parameter

Parameter	Typ	Erforderlich	Beschreibung
issuerId	string	Ja	Die Aussteller-ID (Pfadparameter)
code	string	Ja	Der Verifizierungscode aus der E-Mail

Beispiel

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

Antwort

Ein reiner String:

"issuer has been verified"

---

Aussteller löschen

Löscht einen Aussteller. Mit dem Aussteller dürfen keine Abzeichen verknüpft sein.

DELETE /issuers/{issuerId}

Beispiel

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

Antwort

Ein reiner String:

"issuer has been deleted"

Fehler

• 400 — mit dem Aussteller sind noch Abzeichen verknüpft: issuer has {n} badge(s) linked — delete the badges first. Das Löschen wird ausschließlich durch verknüpfte Abzeichen blockiert — Nachweise verhindern es nicht.
• 404 — Aussteller nicht gefunden

---

Aussteller aktualisieren

Aktualisiert die Felder eines Ausstellers. Nur nicht verifizierte Aussteller können bearbeitet werden — sobald ein Aussteller verifiziert ist, gibt dieser Endpunkt 400 verified issuers cannot be edited zurück, um die Stabilität der Nachweise zu wahren. Beim Bearbeiten eines Ausstellers wird sein Verifizierungscode neu erzeugt: Stimmt die email mit deiner Konto-E-Mail überein, wird der Aussteller automatisch erneut verifiziert, andernfalls wird eine neue Verifizierungs-E-Mail an diese Adresse gesendet.

PUT /issuers/{issuerId}

Parameter

Parameter	Typ	Erforderlich	Beschreibung
issuerId	string	Ja	Die Aussteller-ID (Pfadparameter)
name	string	Nein	Neuer Name
url	string	Nein	Neue URL
email	string	Nein	Neue E-Mail (sendet eine neue Verifizierungs-E-Mail, sofern sie nicht mit deiner Konto-E-Mail übereinstimmt)
logo	string	Nein	Neues Base64-kodiertes Logo
linkedinOrganizationId	string	Nein	Neue LinkedIn-Organisations-ID (oder leerer String zum Löschen)

Antwort

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

Fehler

• 400 — verified issuers cannot be edited (der Aussteller ist bereits verifiziert)
• 400 — not authorized (der Aussteller gehört zu einem anderen Konto)
• 404 — Aussteller nicht gefunden