Authentification

Lisoloo authentifie chaque requête avec un seul en-tête, app-key: YOUR_API_KEY. La clé est par marchand, par environnement, et identifie l’application tout en l’authentifiant.

Le modèle en un paragraphe

Votre backend obtient une api_key depuis le portail développeur une fois. Chaque appel vers $BASE_URL/api/v1/lisoloo/sms-api/* transporte cette clé dans l’en-tête app-key. La passerelle filtre par (group, env, key_type, key_prefix, last4) puis exécute une vérification Argon2id à temps constant contre l’empreinte stockée. Seules les clés en statut allowed (non soft-deleted, non révoquées) s’authentifient ; tout autre statut renvoie 403. La clé en clair est affichée exactement une fois à la génération — les ré-affichages ne renvoient que le préfixe + les 4 derniers caractères.

L’en-tête

POST /api/v1/lisoloo/sms-api/send HTTP/1.1
Host: {BASE_URL}
app-key: sk_live_kqz3pX9aB7nT2vR4wY8eD1fH6jM5oU0i
Content-Type: application/json

{BASE_URL} est l’hôte que vous copiez depuis Tableau de bord Bloonio → Lisoloo → Developer → Clés API. Le tableau de bord affiche des URLs de base séparées pour les environnements sandbox et production.

Le format de la clé est sk_<env>_<32-char-base62> où env ∈ {test, live}. Le préfixe sk_test_* route vers le sandbox ; sk_live_* vers la production. Vous ne pouvez pas utiliser une clé sandbox contre l’URL de production, et vice-versa — voir Environnements.

Où la conserver

Stockage	À utiliser ?
Variable d’environnement sur votre serveur	Oui — recommandé.
Vault / KMS / Secrets Manager	Oui — meilleur pour les régimes de conformité.
En dur dans le code source	Non — risque de fuite.
Côté client (navigateur / app mobile)	Non — la clé a la portée du compte ; toute copie client est compromise.
`.env` versionné dans git	Non.

Si la logique d’envoi SMS doit s’exécuter depuis un client, faites transiter via votre propre backend. N’expédiez jamais la clé vers un navigateur ou un binaire applicatif.

Exemples authentifiés

curl $BASE_URL/api/v1/lisoloo/sms-api/balance \
  -H "app-key: $LISOLOO_API_KEY"

import os
import requests

API_KEY = os.environ["LISOLOO_API_KEY"]

session = requests.Session()
session.headers["app-key"] = API_KEY

balance = session.get(
    "$BASE_URL/api/v1/lisoloo/sms-api/balance",
    timeout=10,
).json()

print(balance["data"]["available_sms"])

const apiKey = process.env.LISOLOO_API_KEY;

const r = await fetch(
  "$BASE_URL/api/v1/lisoloo/sms-api/balance",
  { headers: { "app-key": apiKey } },
);
const { data } = await r.json();
console.log(data.available_sms);

$apiKey = getenv('LISOLOO_API_KEY');

$ch = curl_init('$BASE_URL/api/v1/lisoloo/sms-api/balance');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["app-key: $apiKey"],
]);
$balance = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $balance['data']['available_sms'];

Ce que la passerelle renvoie en cas d’échec d’auth

La passerelle enveloppe les erreurs dans la forme standard FastAPI {"detail": "<texte>"}. Branchez sur le statut HTTP, pas sur le message — les messages sont localisés et peuvent changer.

HTTP	Valeur `detail`	Signification
`401`	`"Missing app-key header. Please provide a valid app-key."`	L’en-tête `app-key` est absent.
`401`	`"Empty app-key header. Please provide a valid app-key."`	L’en-tête est présent mais vide.
`401`	(non autorisé générique)	Le préfixe de clé est faux pour l’environnement, la clé est trop courte, ou la vérification Argon2id a échoué contre toutes les candidates.
`403`	`"Gateway app is pending validation. Please contact support."`	Clé en `pending_validation`.
`403`	`"Gateway app is suspended. Please contact support."`	Clé en `suspended`.
`403`	`"Gateway app has been revoked. Please contact support."`	Clé en `revoqued`.
`403`	`"Gateway app is locked. Please contact support."`	Clé en `locked`.
`403`	`"Gateway app has expired. Please contact support."`	Clé en `expired`.
`403`	`"Gateway app has been rejected. Please contact support."`	Clé en `rejected`.
`500`	`"Authentication service temporarily unavailable. Please try again."`	Exception inattendue pendant la vérification. Retry.

Le middleware ne vous dit délibérément pas quelle candidate a échoué la vérification — il confirme seulement qu’aucune ligne ne correspond, pour éviter de fuiter les collisions de préfixe de clé.

Rotation d’une clé API

Le portail développeur vous permet de régénérer la clé en un clic. La nouvelle clé est affichée en clair sur la même bannière à usage unique qu’à la génération initiale. L’ancienne clé est invalidée immédiatement — il n’y a pas de fenêtre de chevauchement, alors planifiez la bascule :

Générez une nouvelle clé et copiez le texte en clair.
Mettez à jour votre coffre à secrets et redéployez votre service.
Confirmez que le trafic transite par la nouvelle clé (vous verrez last_used_at avancer sur la ligne de la clé).
L’ancienne clé est déjà morte — rien d’autre à faire.

Si vous avez besoin d’une vraie rotation sans coupure avec fenêtre de chevauchement, contactez votre gestionnaire de compte Bloonio — le modèle de clé sous-jacent supporte plusieurs clés actives par marchand ; le portail n’expose que le flux de rotation à clé unique.

Voir aussi

Clés API — visite guidée de la gestion
Environnements — sandbox vs production
Webhooks → Configuration — associer la clé à une URL de livraison
Erreurs — la forme complète des réponses d’erreur