72 lines
1.7 KiB
Markdown
72 lines
1.7 KiB
Markdown
# 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.
|