## Clés API

L'API KennHosting utilise des **clés API Bearer Token** pour l'authentification. Chaque requête doit inclure votre clé dans l'en-tête HTTP `Authorization`.

```http
Authorization: Bearer kh_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Générer une clé API

<Steps>
  <Step title="Accéder aux paramètres API">
    Espace client → **Mon compte → API → Mes clés API**
  </Step>
  <Step title="Créer une nouvelle clé">
    Cliquez sur **Générer une clé API**. Donnez-lui un nom descriptif (ex: "Production - Mon app", "Monitoring").
  </Step>
  <Step title="Définir les permissions">
    Choisissez les permissions de la clé (principe du moindre privilège recommandé) :
    - `services:read` — lire les services (liste et détail)
    - `services:renew` — initier un renouvellement (`POST /v1/services/{uuid}/renew`)
    - `domains:read` — disponibilité (`check`, `check-bulk`) et **devis** (`GET /v1/domains/quote`)
    - `domains:write` — créer une commande d’achat domaine seul (`POST /v1/domains`)
    - `domains:pay` — initier le paiement d'un domaine (`POST /v1/domain-orders/{uuid}/pay`)
    - `domains:dns` — gestion DNS (`/v1/domains/{domain}/dns/...`)
    - `invoices:read` — consulter les factures
    - `invoices:pay` — initier un paiement (`POST /v1/invoices/{uuid}/pay`)
    - `reseller:clients` / `reseller:hosting` / `reseller:domains` / `reseller:vps` — API revendeur
    - `referral:read` / `referral:withdraw` — parrainage
    - `support:read` / `support:write` — tickets
    - `webhooks:read` / `webhooks:write` — webhooks sortants
  </Step>
  <Step title="Copier la clé">
    **Copiez immédiatement la clé affichée.** Elle ne sera plus affichée en clair après cette étape. Si vous la perdez, vous devrez en générer une nouvelle.
  </Step>
</Steps>

<Warning>
  Traitez votre clé API comme un mot de passe. Ne la commitez jamais dans un dépôt Git, ne la partagez pas dans des logs ou des messages. Utilisez des variables d'environnement pour la stocker.
</Warning>

## Format des clés

Les clés API KennHosting ont le format suivant :

| Environnement | Préfixe | Exemple |
|--------------|---------|---------|
| Production | `kh_live_` | `kh_live_abc123...` |
| Sandbox (test) | `kh_test_` | `kh_test_xyz789...` |

## Environnement Sandbox

Utilisez les clés `kh_test_` pour tester vos intégrations sans affecter vos vrais services ni effectuer de vrais paiements.

**URL de base sandbox :**
```
https://kennhosting.com/api/v1
```

Les requêtes sandbox sont identifiées par le préfixe de la clé, pas par une URL différente.

<Warning>
  Les clés **sandbox** (`kh_test_`) sont **strictement en lecture seule** sur l’API générale : toute requête **POST**, **PUT**, **PATCH** ou **DELETE** reçoit **`403 Forbidden`** avec le code `sandbox_read_only`. **Exception :** l’API revendeur gère son propre mode sandbox — les opérations d’écriture (provision, wallet sandbox, domaines) y sont simulées même avec une clé `kh_test_`. Pour l’API générale (commandes, paiements, tickets), utilisez une clé **live** (`kh_live_`) sur un compte de test dédié.
</Warning>

## Rotation des clés

Bonne pratique : **faites tourner vos clés régulièrement**, au minimum tous les 6 mois ou immédiatement en cas de compromission suspectée.

1. Générez une nouvelle clé avec les mêmes permissions
2. Mettez à jour la variable d'environnement dans vos applications
3. Vérifiez que les applications fonctionnent avec la nouvelle clé
4. Révoquez l'ancienne clé

## Révoquer une clé

**Mon compte → API → Mes clés API → [clé] → Révoquer**

La révocation est immédiate. Toute requête utilisant cette clé retournera `401 Unauthorized`.

## Exemple d'utilisation sécurisée

**.env (jamais commité)**
```
KENNHOSTING_API_KEY=kh_live_xxxxxxxxxxxxxxxxxxxx
```

**config/services.php (Laravel)**
```php
'kennhosting' => [
    'api_key' => env('KENNHOSTING_API_KEY'),
    'base_url' => 'https://kennhosting.com/api/v1',
],
```

**KennHostingClient.php**
```php
class KennHostingClient
{
    private string $apiKey;

    public function __construct()
    {
        $this->apiKey = config('services.kennhosting.api_key');
    }

    public function request(string $method, string $endpoint, array $data = []): array
    {
        $response = Http::withToken($this->apiKey)
            ->acceptJson()
            ->{$method}(config('services.kennhosting.base_url') . '/' . $endpoint, $data);

        return $response->json();
    }
}
```