# 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.

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](/v1.0/cles-api/obtenir-une-cle-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"
```

```ts
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 :

```ts title="wakastart.ts"
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 :

```ts
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 :

```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

- [Référence API : Authentification](/v1.0/reference-api/authentification-api) : les trois modes d'authentification de l'API.
- [Résoudre les problèmes de clés API](/v1.0/cles-api/depannage).
- [Codes d'erreur](/v1.0/codes-d-erreur).
