# Accès API via clés API

---

## Vue d'ensemble

En plus du JWT, Xpeditis supporte l'authentification par **clé API** pour les intégrations tierces.

---

## Format

```
Header: x-api-key: xped_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Le préfixe `xped_` est toujours visible. Le reste est une chaîne aléatoire sécurisée.
La clé complète est hashée avec Argon2 — impossible de la retrouver après création.

---

## Gestion des clés

| Méthode | Route | Description |
|---------|-------|-------------|
| GET | /api/v1/api-keys | Liste les clés de l'organisation |
| POST | /api/v1/api-keys | Créer une nouvelle clé |
| PATCH | /api/v1/api-keys/:id | Renommer / désactiver |
| DELETE | /api/v1/api-keys/:id | Supprimer |

### Créer une clé

```
POST /api/v1/api-keys
Authorization: Bearer <jwt>

{ "name": "Integration ERP" }
```

Réponse (unique — la clé complète n'est retournée qu'une seule fois) :
```json
{
  "id": "uuid",
  "name": "Integration ERP",
  "key": "xped_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "keyPrefix": "xped_xxxx",
  "createdAt": "2026-05-13T10:00:00Z"
}
```

---

## Permissions

Les clés API héritent des permissions de l'organisation. Elles ne peuvent pas avoir plus de droits que le compte utilisateur qui les a créées.

---

## Sécurité

- Stockage : hash Argon2 uniquement (pas de récupération possible)
- Expiration : configurable (`expires_at`, null = pas d'expiration)
- Révocation immédiate : `DELETE /api/v1/api-keys/:id`
- Suivi : `last_used_at` mis à jour à chaque utilisation

---

## Endpoints supportant les clés API

Tous les endpoints protégés acceptent soit un JWT soit une clé API.
Voir `apps/backend/src/application/guards/api-key-or-jwt.guard.ts` pour l'implémentation.