Clés API

Le portail développeur Bloonio → Lisoloo → Developer → Clés API est l’endroit où vous gérez l’unique clé API liée à votre compte marchand. Cette page est une visite guidée de chaque contrôle.

Générer une clé

Si votre compte n’a pas encore de clé, le portail affiche un état vide avec un bouton Générer la clé API. En cliquant :

Une nouvelle api_key est créée côté serveur et son empreinte Argon2id est stockée.
La clé en clair est retournée dans la réponse, une seule fois.
Une bannière jaune à usage unique s’affiche avec la clé en clair, un bouton Copier dans le presse-papier et un bouton Je l’ai copiée pour fermer.

Après fermeture de la bannière, la clé en clair est irrécupérable. Le portail n’affiche plus que le préfixe et les 4 derniers caractères ensuite — par exemple sk_live_kqz3…oU0i.

Métadonnées de la clé

Une fois la clé existante, le portail affiche une carte avec six champs :

Champ	Source	Notes
ID de clé	`identifier`	Stable, public, sûr à logger. À utiliser pour contacter le support.
Type	`key_type`	Toujours `sms_api` pour l’instant.
Statut	`status_lbl`	`ACTIVE`, `SUSPENDED`, `EXPIRED`. Déclenche la réponse `403` ci-dessus.
Environnement	`environment`	`sandbox` ou `production`, correspondant au préfixe.
Créée	`created_at`	Horodatage de la première émission.
Dernière utilisation	`last_used_at`	Mis à jour à chaque requête réussie. `Jamais` si la clé n’a jamais authentifié un appel.

La clé complète en clair n’est jamais retournée une seconde fois — le champ Votre clé API n’affiche que la forme masquée (sk_live_kqz3…oU0i).

Régénérer

Cliquez sur Régénérer la clé pour faire tourner. Le portail confirme avec une modale — cela invalide l’ancienne clé immédiatement. À la confirmation, une nouvelle clé en clair apparaît sur la même bannière à usage unique.

À utiliser quand :

Vous suspectez une fuite (committée dans un dépôt public, postée dans un ticket de support, incluse dans une capture d’écran).
Un membre de l’équipe avec accès au coffre à secrets est parti.
Cela fait ≥12 mois depuis la dernière rotation (bonne hygiène, pas une exigence stricte).

L’opération de régénération ne préserve pas last_used_at, la configuration webhook, ou aucune autre métadonnée — seule la clé en clair est nouvelle. L’URL webhook et les identifiants Basic auth persistent à travers les rotations.

Configurer un webhook sur la clé

Sous la carte de la clé API, le portail expose un formulaire Configuration webhook avec trois champs :

webhook_url (requis pour activer les webhooks) — l’URL HTTPS vers laquelle la passerelle POST les accusés de livraison.
webhook_basic_auth_username (optionnel) — le nom d’utilisateur pour l’auth HTTP Basic sur les appels sortants.
webhook_basic_auth_password (write-only) — le mot de passe. Le portail ne l’affiche jamais après l’enregistrement ; le drapeau webhook_basic_auth_configured: true sur la ligne de la clé API confirme qu’il est défini.

Voir Webhooks → Configuration pour le flux complet et les charges utiles d’événements.

États de statut

Le champ de statut reflète l’enum backend EApplicationKeysStatus. Seules les clés allowed s’authentifient ; tout le reste renvoie 403.

Statut	Résultat auth	Signification	Action
`allowed`	✓ passe	Clé active et vérifiée.	Rien — état normal.
`pending_validation`	`403`	Clé créée mais pas encore activée par Bloonio.	Contactez votre gestionnaire de compte pour activer.
`suspended`	`403`	Suspendue manuellement (facturation, conformité, revue anti-abus).	Contactez votre gestionnaire de compte.
`revoqued`	`403`	Marquée révoquée.	Régénérez si vous avez encore besoin de l’intégration.
`locked`	`403`	Verrouillée temporairement (typiquement par des contrôles automatiques de risque).	Contactez le support.
`expired`	`403`	Expiration matérielle dépassée.	Régénérez.
`rejected`	`403`	Application rejetée à l’onboarding.	Contactez votre gestionnaire de compte.

De plus, les clés avec soft_deleted: true ou un horodatage revoked_at non-null sont filtrées au niveau de la base et apparaissent comme un 401 générique (le middleware ne différencie pas délibérément pour qu’un attaquant ne puisse pas savoir si un essai a touché une ligne supprimée).

Liste de contrôle sécurité

La clé vit dans une variable d’environnement côté serveur ou dans un gestionnaire de secrets, jamais dans le code client.
.env est dans .gitignore.
CI/CD masque la valeur dans les logs.
Les récepteurs webhook vérifient que les identifiants HTTP Basic correspondent à la paire configurée (voir Webhooks → Configuration).
En cas de fuite suspectée, faites tourner avant de révoquer — le portail effectue cela atomiquement via Régénérer.