# Clé API

Les clés API authentifient les appels serveur-à-serveur aux APIs de The Wallet Crew. Les clés API sont limitées à un tenant. Une clé ne fonctionne que pour un seul tenant. Les intégrations couvrant plusieurs tenants nécessitent une clé par tenant.

Les clés API peuvent également être restreintes par scopes. Le principe du moindre privilège réduit le risque et limite la portée des incidents.

<details>

<summary>Exemples concrets</summary>

* Un job CRM de marque met à jour les points de fidélité chaque nuit, puis déclenche des mises à jour de Carte.
* Un middleware d'intégration émet de nouvelles Cartes après un événement de paiement e‑commerce.
* Un pipeline de données récupère le statut d'installation des Cartes et l'envoie vers l'analytique.

</details>

### Avant de commencer

* Un compte admin avec accès à **Paramètres** est requis.
* L'utilisation prévue et le système propriétaire sont identifiés (service, job, connecteur).
* Les scopes minimaux requis sont listés. Chaque endpoint API documente ses scopes requis, et la console d'administration affiche les scopes disponibles lors de la création de la clé.

{% hint style="warning" %}
N'envoyez jamais une clé API dans une application mobile ou dans du JavaScript côté client. Traitez-la comme un mot de passe.
{% endhint %}

### Créer une clé API

{% stepper %}
{% step %}

#### Ouvrir Clés API

1. Connectez‑vous à la console d'administration.
2. Aller à **Paramètres → Sécurité → Clés API**.

<p align="center"><a href="https://admin.thewalletcrew.io/tenant/~/settings/security/apiKeys" class="button secondary" data-icon="chevrons-right">The Wallet Crew - Clés API</a></p>
{% endstep %}

{% step %}

#### Ajouter une nouvelle clé

1. Cliquez **Ajouter nouveau**.
2. Donnez un nom clair.
   * Exemple : `crm-sync-prod` ou `nightly-pass-update`.
3. Sélectionnez les scopes dont vous avez besoin.
4. Cliquez **Enregistrer**.
   {% endstep %}

{% step %}

#### Copiez et stockez la clé

La valeur de la clé n'est affichée qu'une seule fois, juste après la création. Après la fermeture de la boîte de dialogue, la valeur ne peut pas être récupérée.

La clé doit être stockée dans un gestionnaire de secrets. L'accès en lecture doit être limité au plus petit ensemble de services et d'opérateurs nécessaires au fonctionnement de l'intégration.
{% endstep %}
{% endstepper %}

### Utiliser la clé dans les requêtes API

Envoyez la clé dans l'en‑tête `X-API-KEY` .

Exemple d'en‑tête :

`X-API-KEY : <your_api_key>`

La liste complète des endpoints et les formats requête/réponse sont disponibles dans la [référence API](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/develop/api-reference).

#### Valider l'accès rapidement

Les échecs d'authentification et d'autorisation se ressemblent, mais nécessitent des corrections différentes. Un flux de validation rapide aide à isoler le problème tôt.

Exécutez une `GET` requête à faible impact qui corresponde aux scopes sélectionnés. Un `401 Unauthorized` réponse indique généralement une clé manquante, invalide ou révoquée. Un `403 Forbidden` réponse indique généralement une clé valide avec des scopes insuffisants.

### Gérer, faire pivoter, révoquer

* **Faire pivoter** les clés régulièrement.
  * Créez une nouvelle clé.
  * Déployez‑la vers vos services.
  * Révoquez l'ancienne clé après une courte période de chevauchement.
* **Révoquer** les clés immédiatement si elles fuient.
* Conservez des clés séparées par environnement et intégration.

### Dépannage

* **401 Unauthorized**
  * Manquant ou invalide `X-API-KEY` .
  * La clé a été révoquée.
* **403 Forbidden**
  * La clé est valide mais manque le scope requis.

### FAQ

<details>

<summary>Une clé API peut‑elle être utilisée sur plusieurs tenants ?</summary>

Non. Les clés API sont limitées au tenant. Chaque tenant nécessite sa propre clé, même lorsque la même intégration s'exécute dans plusieurs tenants.

</details>

<details>

<summary>Une clé API peut‑elle être récupérée plus tard si elle n'a pas été copiée ?</summary>

Les clés API sont destinées à être affichées une seule fois lors de leur création. Si la valeur est perdue, la voie la plus sûre est de révoquer l'ancienne clé et d'en créer une nouvelle.

</details>

<details>

<summary>Quelle est la meilleure façon de nommer les clés API ?</summary>

Un nom doit identifier le système propriétaire et l'environnement. Des noms comme `crm-sync-prod` ou `data-export-staging` rendent la rotation et la réponse aux incidents beaucoup plus rapides.

</details>

<details>

<summary>Comment faire pivoter les clés sans temps d'arrêt ?</summary>

Créez une nouvelle clé et déployez‑la en premier. Gardez les deux clés actives pendant une courte période de chevauchement. Révoquez l'ancienne clé une fois que les logs confirment que la nouvelle clé est utilisée partout.

</details>

<details>

<summary>Où se trouve la référence des scopes ?</summary>

Chaque endpoint API documente les scopes requis dans sa propre documentation.

La console d'administration reste l'endroit où les scopes disponibles peuvent être consultés et sélectionnés lors de la création ou de la modification d'une clé.

</details>