Appeler l'API avec une clé
Authentifier un appel à l'API publique Wakastart avec l'en-tête x-api-key, en cURL et en TypeScript, et traiter les erreurs.
- Duration
- 10 min
This page has not been translated yet and is shown in French.
Une clé API s'envoie dans l'en-tête x-api-key de chaque requête vers l'API publique. Ce guide fait un premier appel, lister les utilisateurs du client de la clé, puis montre comment encapsuler l'appel et traiter les erreurs.
Avant de commencer
- Vous disposez d'une clé dont le profil porte le droit
users.readet dont le niveau est au moins Administrateur client (voir Obtenir une clé API). - La clé est disponible dans la variable d'environnement
WAKASTART_API_KEYde votre serveur.
Faire un premier appel
Listez les utilisateurs du client de la clé :
curl -s "https://api.wakastart.app/api/config/users?page=1&limit=20" \
-H "x-api-key: $WAKASTART_API_KEY"const response = await fetch("https://api.wakastart.app/api/config/users?page=1&limit=20", {
headers: { "x-api-key": process.env.WAKASTART_API_KEY! },
});
const users = await response.json();Réponse attendue (extrait) :
{
"data": [
{
"id": "6b0f7a52-1d2e-4c3b-9a8f-0e1d2c3b4a59",
"wid": "EXUSR1",
"email": "claire.martin@exemple.fr",
"firstName": "Claire",
"lastName": "Martin",
"customerId": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"customerName": "Clinique Exemple",
"isActive": true
}
],
"meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}La liste est limitée au client de la clé, quels que soient les filtres envoyés.
Encapsuler les appels
Centralisez l'en-tête et le traitement des erreurs dans une fonction :
const API_URL = "https://api.wakastart.app/api";
export class WakastartApiError extends Error {
constructor(public status: number, public body: { message?: string | string[] }) {
super(Array.isArray(body.message) ? body.message.join(", ") : body.message ?? `HTTP ${status}`);
}
}
export async function wakastart<T>(path: string, init: RequestInit = {}): Promise<T> {
const headers = new Headers(init.headers);
headers.set("x-api-key", process.env.WAKASTART_API_KEY!);
headers.delete("authorization"); // un en-tête Authorization ferait ignorer la clé
if (init.body) headers.set("Content-Type", "application/json");
const response = await fetch(`${API_URL}${path}`, { ...init, headers });
const body = await response.json().catch(() => ({}));
if (!response.ok) throw new WakastartApiError(response.status, body);
return body as T;
}Exemple d'usage :
const { data } = await wakastart<{ data: { email: string }[] }>("/config/users?limit=100");
console.log(data.map((u) => u.email));Traiter les erreurs
| Statut | Message | Que faire |
|---|---|---|
401 | Cle API utilisateur invalide ou expiree | Clé inconnue, révoquée, désactivée, expirée ou utilisée depuis une adresse non autorisée : ne réessayez pas, alertez |
403 | Droit applicatif requis : users.read | Le profil de la clé ne porte pas ce droit |
403 | Niveau d'administration insuffisant. Requis: CUSTOMER_ADMIN, Actuel: NONE | Le niveau de la clé est trop bas pour l'opération |
429 | ThrottlerException: Too Many Requests | Limite de débit par adresse IP atteinte : réessayez plus tard, avec un délai croissant |
Les erreurs suivent le format commun de l'API :
{
"statusCode": 403,
"message": "Droit applicatif requis : users.read",
"error": "Forbidden",
"timestamp": "2026-10-23T09:12:44.512Z",
"path": "/api/config/users"
}Vérifier le résultat
Votre serveur obtient 200 et la liste des utilisateurs du client. Dans les journaux de votre serveur, seuls les 10 premiers caractères de la clé apparaissent, jamais la clé complète.
Voir aussi
- Référence API : Authentification : les trois modes d'authentification de l'API.
- Résoudre les problèmes de clés API.
- Codes d'erreur.