Aller au contenu

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.

GuideDéveloppeur
Durée
10 min
Voir en Markdown

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.read et dont le niveau est au moins Administrateur client (voir Obtenir une clé API).
  • La clé est disponible dans la variable d'environnement WAKASTART_API_KEY de votre serveur.

Faire un premier appel

Listez les utilisateurs du client de la clé :

Bash
curl -s "https://api.wakastart.app/api/config/users?page=1&limit=20" \
  -H "x-api-key: $WAKASTART_API_KEY"
TypeScript
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) :

JSON
{
  "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 :

wakastart.tsTypeScript
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 :

TypeScript
const { data } = await wakastart<{ data: { email: string }[] }>("/config/users?limit=100");
console.log(data.map((u) => u.email));

Traiter les erreurs

StatutMessageQue faire
401Cle API utilisateur invalide ou expireeClé inconnue, révoquée, désactivée, expirée ou utilisée depuis une adresse non autorisée : ne réessayez pas, alertez
403Droit applicatif requis : users.readLe profil de la clé ne porte pas ce droit
403Niveau d'administration insuffisant. Requis: CUSTOMER_ADMIN, Actuel: NONELe niveau de la clé est trop bas pour l'opération
429ThrottlerException: Too Many RequestsLimite 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 :

JSON
{
  "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