API-sleutels

Met API-sleutels krijg je programmatisch toegang tot de badges.ninja REST API. Gebruik ze om het aanmaken, uitgeven en beheren van badges te automatiseren vanuit je eigen applicaties.

Een API-sleutel aanmaken

1. Open de pagina API Keys in de zijbalk.
2. Klik op Create API Key. Er opent een inline formulier:

3. Geef de sleutel een naam en klik op Create. De volledige sleutel wordt eenmalig getoond in een groene banner:

4. Kopieer de sleutel direct — de volledige sleutel wordt maar één keer getoond. Als je hem kwijtraakt, moet je een nieuwe aanmaken. Nadat je de banner hebt gesloten, toont het dashboard alleen nog het voorvoegsel van de sleutel (bijv. bws_a1b2c3d4...); de volledige sleutel blijft server-side opgeslagen om je verzoeken te authenticeren:

Elke rij toont ook wanneer de sleutel is aangemaakt en, zodra hij is gebruikt, een last used-tijdstempel zodat je verouderde sleutels kunt opsporen.

Toegangsbereik

Bij het aanmaken van een sleutel kun je hem alleen-lezen maken of volledige toegang laten behouden:

Bereik	Staat toe
Volledige toegang (standaard)	Lezen en schrijven — gegevens opvragen en aanmaken, uitgeven, bijwerken of verwijderen.
Alleen-lezen	Alleen veilige GET-verzoeken. Elk verzoek dat gegevens wijzigt (POST, PUT, PATCH, DELETE) wordt geweigerd met 403 Forbidden.

Gebruik een alleen-lezen sleutel voor integraties die je gegevens alleen hoeven te lezen (rapportage, dashboards, back-ups), zodat een gelekte sleutel niets kan wijzigen. Vink Read-only key aan in het aanmaakformulier; alleen-lezen sleutels tonen een Read-only-badge in de lijst. Sleutels die zijn aangemaakt voordat er bereiken bestonden, behouden volledige toegang.

Sleutelformaat

API-sleutels gebruiken het voorvoegsel bws_ gevolgd door een hex-string van 32 tekens:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

API-sleutels gebruiken in verzoeken

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

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

Zie de pagina Authenticatie voor alle details over API-authenticatie.

Sleutellimieten per abonnement

Het aantal API-sleutels dat je kunt aanmaken, hangt af van je abonnement:

Abonnement	Limiet API-sleutels
Free	1
Starter ($9/mo)	5
Pro ($29/mo)	20

Vervaldatum van sleutels

Elke API-sleutel verloopt één jaar na het aanmaken. Zodra een sleutel is verlopen, authenticeert hij geen verzoeken meer, precies alsof hij was verwijderd. Maak een nieuwe sleutel aan voordat de oude verloopt om onderbrekingen te voorkomen.

Een sleutel verwijderen

1. Open de pagina API Keys.
2. Zoek de sleutel die je wilt verwijderen.
3. Klik op Delete.
4. Bevestig het verwijderen.

Na het verwijderen werkt de sleutel direct niet meer. Alle applicaties die die sleutel gebruiken, krijgen authenticatiefouten.