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) :

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

1.7 KiB Raw Blame History