Authentification

Toutes les requêtes vers l'API badges.ninja nécessitent une authentification. Cette page explique comment authentifier vos requêtes.

URL de base

https://api.badges.ninja

Tous les endpoints de l'API sont relatifs à cette URL de base.

Authentification par clé API

La méthode d'authentification principale est une clé API passée dans l'en-tête X-Api-Key.

Obtenir une clé API

Depuis le tableau de bord :

Connectez-vous sur badges.ninja.
Allez dans Clés API dans la barre latérale.
Cliquez sur Créer une clé API.
Copiez la clé (elle n'est affichée qu'une seule fois).

Depuis l'API :

Les clés API peuvent aussi être gérées via l'API en utilisant votre token JWT issu du flux d'authentification Cognito. Consultez le tableau de bord pour l'approche la plus simple.

Utiliser votre clé API

Incluez l'en-tête X-Api-Key dans chaque requête :

bash

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

Format de la clé API

Les clés utilisent le préfixe bws_ :

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Format des requêtes

Les requêtes GET passent les paramètres dans la query string
Les requêtes POST et PUT envoient un corps JSON avec un objet parameters
Toutes les réponses renvoient du JSON avec Content-Type: application/json

Structure d'une requête POST/PUT

json

{
  "parameters": {
    "name": "Mon badge",
    "description": "Un badge d'exemple"
  }
}

Exemple de requête

bash

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

Exemple de réponse

json

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

Limites de débit

Les requêtes API sont soumises à une limitation de débit. Si vous dépassez la limite, vous recevez une réponse 429 Too Many Requests. Attendez quelques secondes puis réessayez.

Endpoints publics

Certains endpoints ne nécessitent pas d'authentification. Ce sont les endpoints publics de vérification sous /certify-badge/ qui permettent à quiconque de vérifier les certifications.

Authentification ​

URL de base ​

Authentification par clé API ​

Obtenir une clé API ​

Utiliser votre clé API ​

Format de la clé API ​

Format des requêtes ​

Structure d'une requête POST/PUT ​

Exemple de requête ​

Exemple de réponse ​

Limites de débit ​

Endpoints publics ​