API-Schlüssel

Mit API-Schlüsseln greifst du programmatisch auf die REST-API von badges.ninja zu. Nutze sie, um das Erstellen, Ausstellen und Verwalten von Auszeichnungen aus deinen eigenen Anwendungen zu automatisieren.

Einen API-Schlüssel erstellen

1. Öffne die Seite API Keys in der Seitenleiste.
2. Klicke auf Create API Key. Ein eingebettetes Formular öffnet sich:

3. Gib dem Schlüssel einen Namen und klicke auf Create. Der vollständige Schlüssel wird nur einmal in einem grünen Banner angezeigt:

4. Kopiere den Schlüssel sofort — der vollständige Schlüssel wird nur einmal angezeigt. Wenn du ihn verlierst, musst du einen neuen erstellen. Nachdem du das Banner geschlossen hast, zeigt das Dashboard nur noch das Präfix des Schlüssels an (z. B. bws_a1b2c3d4...); der vollständige Schlüssel bleibt serverseitig gespeichert, um deine Anfragen zu authentifizieren:

Jede Zeile zeigt außerdem, wann der Schlüssel erstellt wurde, und – sobald er verwendet wurde – einen Zeitstempel für zuletzt verwendet, damit du veraltete Schlüssel erkennst.

Zugriffsbereiche

Beim Erstellen eines Schlüssels kannst du ihn schreibgeschützt machen oder mit vollem Zugriff belassen:

Bereich	Erlaubt
Voller Zugriff (Standard)	Lesen und Schreiben — Daten auflisten sowie erstellen, ausstellen, aktualisieren oder löschen.
Schreibgeschützt	Nur sichere GET-Anfragen. Jede verändernde Anfrage (POST, PUT, PATCH, DELETE) wird mit 403 Forbidden abgelehnt.

Verwende einen schreibgeschützten Schlüssel für Integrationen, die deine Daten nur lesen müssen (Berichte, Dashboards, Backups), damit ein kompromittierter Schlüssel nichts verändern kann. Aktiviere im Erstellungsformular Read-only key; schreibgeschützte Schlüssel zeigen in der Liste ein Read-only-Abzeichen. Schlüssel, die vor der Einführung der Bereiche erstellt wurden, behalten vollen Zugriff.

Schlüsselformat

API-Schlüssel verwenden das Präfix bws_, gefolgt von einem 32-stelligen Hex-String:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

API-Schlüssel in Anfragen verwenden

Füge den API-Schlüssel im Header X-Api-Key jeder API-Anfrage hinzu:

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

Alle Details zur API-Authentifizierung findest du auf der Seite Authentifizierung.

Schlüssellimits pro Tarif

Die Anzahl der API-Schlüssel, die du erstellen kannst, hängt von deinem Tarif ab:

Tarif	Limit für API-Schlüssel
Free	1
Starter ($9/mo)	5
Pro ($29/mo)	20

Ablauf von Schlüsseln

Jeder API-Schlüssel läuft ein Jahr nach seiner Erstellung ab. Sobald ein Schlüssel abgelaufen ist, authentifiziert er keine Anfragen mehr – genau so, als wäre er gelöscht worden. Erstelle einen neuen Schlüssel, bevor der alte abläuft, um Unterbrechungen zu vermeiden.

Einen Schlüssel löschen

1. Öffne die Seite API Keys.
2. Suche den Schlüssel, den du löschen möchtest.
3. Klicke auf Delete.
4. Bestätige das Löschen.

Nach dem Löschen funktioniert der Schlüssel sofort nicht mehr. Alle Anwendungen, die diesen Schlüssel verwenden, erhalten Authentifizierungsfehler.