Authentifizierung

Alle API-Anfragen an badges.ninja erfordern Authentifizierung. Diese Seite erklärt, wie du deine Anfragen authentifizierst.

Basis-URL

https://api.badges.ninja

Alle API-Endpunkte sind relativ zu dieser Basis-URL.

Authentifizierung per API-Schlüssel

Die primäre Authentifizierungsmethode ist ein API-Schlüssel, der im X-Api-Key-Header übergeben wird.

API-Schlüssel erhalten

Aus dem Dashboard:

1. Melde dich bei badges.ninja an.
2. Gehe in der Seitenleiste zu API-Schlüssel.
3. Klicke auf API-Schlüssel erstellen.
4. Kopiere den Schlüssel (er wird nur einmal angezeigt).

Aus der API:

API-Schlüssel lassen sich auch per API verwalten — dazu nutzt du dein JWT-Token aus dem Cognito-Authentifizierungsflow. Für den einfachsten Weg siehe das Dashboard.

Den API-Schlüssel verwenden

Füge den X-Api-Key-Header in jede Anfrage ein:

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

Format des API-Schlüssels

Schlüssel nutzen das Präfix bws_:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Anfrageformat

• GET-Anfragen übergeben Parameter als Query-String
• POST- und PUT-Anfragen senden einen JSON-Body mit einem parameters-Objekt
• Alle Antworten liefern JSON mit Content-Type: application/json

Struktur einer POST/PUT-Anfrage

{
  "parameters": {
    "name": "Meine Auszeichnung",
    "description": "Eine Beispielauszeichnung"
  }
}

Beispielanfrage

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": "Meine Organisation",
      "url": "https://example.com",
      "email": "admin@example.com"
    }
  }'

Beispielantwort

{
  "statusCode": 200,
  "info": {
    "issuerId": "https://api.badges.ninja/certify-badge/issuer/abc123-def456"
  }
}

Ratenlimits

API-Anfragen unterliegen einer Ratenbegrenzung. Wenn du das Limit überschreitest, erhältst du eine 429 Too Many Requests-Antwort. Warte ein paar Sekunden und versuche es erneut.

Öffentliche Endpunkte

Einige Endpunkte erfordern keine Authentifizierung. Das sind die öffentlichen Verifizierungs-Endpunkte unter /certify-badge/, die jeder zum Verifizieren von Auszeichnungsnachweisen nutzen kann.