Clés API

Les clés API vous permettent d'accéder à l'API REST de badges.ninja de manière programmatique. Utilisez-les pour automatiser la création, l'émission et la gestion des badges depuis vos propres applications.

Créer une clé API

1. Ouvrez la page Clés API dans la barre latérale.
2. Cliquez sur Créer une clé API. Un formulaire en ligne s'ouvre :

3. Donnez un nom à la clé et cliquez sur Créer. La clé complète est révélée une seule fois dans un bandeau vert :

4. Copiez la clé immédiatement : la clé complète n'est affichée qu'une seule fois. Si vous la perdez, vous devrez en créer une nouvelle. Après la fermeture du bandeau, le tableau de bord n'affiche plus que le préfixe de la clé (p. ex. bws_a1b2c3d4...) ; la clé complète reste stockée côté serveur pour authentifier vos requêtes :

Chaque ligne indique aussi la date de création de la clé et, une fois qu'elle a été utilisée, un horodatage de dernière utilisation pour repérer les clés inactives.

Scopes d'accès

Lorsque vous créez une clé, vous pouvez la rendre en lecture seule ou la laisser en accès complet :

Scope	Autorise
Accès complet (par défaut)	Lecture et écriture : lister des données, et créer, émettre, mettre à jour ou supprimer.
Lecture seule	Uniquement les requêtes GET sûres. Toute requête modifiante (POST, PUT, PATCH, DELETE) est rejetée avec 403 Forbidden.

Utilisez une clé en lecture seule pour les intégrations qui n'ont besoin que de lire vos données (rapports, tableaux de bord, sauvegardes), afin qu'une clé divulguée ne puisse rien modifier. Cochez Clé en lecture seule dans le formulaire de création ; les clés en lecture seule affichent un badge Lecture seule dans la liste. Les clés créées avant l'existence des scopes conservent l'accès complet.

Format de la clé

Les clés API utilisent le préfixe bws_ suivi d'une chaîne hexadécimale de 32 caractères :

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Utiliser les clés API dans les requêtes

Incluez la clé API dans l'en-tête X-Api-Key de chaque requête API :

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

Consultez la page Authentification pour tous les détails sur l'authentification de l'API.

Limites de clés par forfait

Le nombre de clés API que vous pouvez créer dépend de votre forfait :

Forfait	Limite de clés API
Free	1
Starter ($9/mo)	5
Pro ($29/mo)	20

Expiration des clés

Chaque clé API expire un an après sa création. Une fois expirée, une clé n'authentifie plus les requêtes, exactement comme si elle avait été supprimée. Créez une nouvelle clé avant l'expiration de l'ancienne pour éviter toute interruption.

Supprimer une clé

1. Ouvrez la page Clés API.
2. Trouvez la clé à supprimer.
3. Cliquez sur Supprimer.
4. Confirmez la suppression.

Une fois supprimée, la clé cesse immédiatement de fonctionner. Toute application utilisant cette clé recevra des erreurs d'authentification.