Authenticatie

Alle API-verzoeken aan badges.ninja vereisen authenticatie. Op deze pagina leggen we uit hoe je je verzoeken authenticeert.

Basis-URL

https://api.badges.ninja

Alle API-endpoints zijn relatief aan deze basis-URL.

Authenticatie met API-sleutel

De primaire authenticatiemethode is een API-sleutel die je meegeeft in de X-Api-Key-header.

Een API-sleutel verkrijgen

Vanuit het dashboard:

1. Meld je aan op badges.ninja.
2. Ga naar API-sleutels in de zijbalk.
3. Klik op API-sleutel aanmaken.
4. Kopieer de sleutel (wordt slechts één keer getoond).

Via de API:

API-sleutels kunnen ook via de API worden beheerd met je JWT-token uit de Cognito-authenticatiestroom. Voor de eenvoudigste aanpak gebruik je het dashboard.

Je API-sleutel gebruiken

Voeg de X-Api-Key-header toe aan elk verzoek:

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

Formaat van de API-sleutel

Sleutels gebruiken het voorvoegsel bws_:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Verzoekformaat

• GET-verzoeken geven parameters mee als query strings
• POST- en PUT-verzoeken sturen een JSON-body met een parameters-object
• Alle antwoorden retourneren JSON met Content-Type: application/json

Structuur van POST/PUT-verzoeken

{
  "parameters": {
    "name": "My Badge",
    "description": "A sample badge"
  }
}

Voorbeeldverzoek

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

Voorbeeldantwoord

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

Snelheidslimieten

API-verzoeken zijn onderhevig aan snelheidsbeperking. Overschrijd je de limiet, dan krijg je een 429 Too Many Requests-respons. Wacht enkele seconden en probeer het opnieuw.

Publieke endpoints

Sommige endpoints vereisen geen authenticatie. Het gaat om de publieke verificatie-endpoints onder /certify-badge/, waarmee iedereen badgereferenties kan verifiëren.