Authentification
Clés API, tokens JWT et scopes de permissions
3 min de lecture
Sur cette page
Méthodes d'authentification
Kataio prend en charge deux méthodes d'authentification. Choisissez celle qui correspond à votre cas d'usage :
| Méthode | Idéal pour | Durée de vie |
|---|---|---|
| Clé API | Intégrations serveur-à-serveur | Jusqu'à révocation |
| Token JWT Bearer | Sessions authentifiées utilisateur | 1 heure (configurable) |
Authentification par clé API
Envoyez votre clé API dans l'en-tête X-API-Key avec chaque requête :
cURL
curl -X GET "https://app.kataio.com/api/v1/products" \
-H "X-API-Key: pk_live_abc123def456"JavaScript
const response = await fetch(
"https://app.kataio.com/api/v1/products",
{
headers: { "X-API-Key": "pk_live_abc123def456" },
}
);PHP
$client = new GuzzleHttp\Client();
$response = $client->get(
"https://app.kataio.com/api/v1/products",
[
"headers" => [
"X-API-Key" => "pk_live_abc123def456",
],
]
);Python
import requests
response = requests.get(
"https://app.kataio.com/api/v1/products",
headers={"X-API-Key": "pk_live_abc123def456"}
)C#
using var client = new HttpClient();
client.DefaultRequestHeaders.Add(
"X-API-Key", "pk_live_abc123def456");
var response = await client.GetAsync(
"https://app.kataio.com/api/v1/products");Token JWT Bearer
Pour les flux authentifiés par utilisateur, obtenez d'abord un token JWT en envoyant vos identifiants au endpoint de connexion :
POST /api/v1/auth/login
Content-Type: application/json
{
"email": "utilisateur@exemple.com",
"password": "votre_mot_de_passe"
}La réponse inclut un accessToken et un refreshToken :
{
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "eyJhbGciOiJIUzI1NiIs...",
"expiresIn": 3600
}Utilisez le token d'accès dans l'en-tête Authorization :
curl -X GET "https://app.kataio.com/api/v1/products" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."Renouvellement des tokens
Lorsque le token d'accès expire, utilisez le refresh token pour en obtenir un nouveau :
POST /api/v1/auth/refresh
Content-Type: application/json
{
"refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}Scopes de permissions
Les clés API peuvent être limitées par scope. Scopes disponibles :
| Scope | Description |
|---|---|
read:products | Lire les données produit |
write:products | Créer, modifier, supprimer des produits et variantes |
read:categories | Lire les catégories |
write:categories | Gérer les catégories |
read:attributes | Lire les attributs et groupes d'attributs |
write:attributes | Créer, modifier, supprimer les attributs, options et axes de variation |
read:orders | Lire les données de commande |
write:orders | Créer des commandes, mettre à jour le statut (avec suivi de livraison), créer des retours et supprimer des commandes |
read:inventory | Lire les niveaux de stock |
write:inventory | Ajuster le stock, créer des transferts et mouvements |
read:channels | Lire les configurations de canaux |
write:channels | Gérer les connexions de canaux |
read:customers | Lire les clients |
write:customers | Créer, modifier, fusionner des clients |
read:webhooks | Lister les abonnements webhook et les livraisons |
write:webhooks | Créer, modifier, supprimer les abonnements webhook |
read:analytics | Lire les KPI, revenus et analyses de complétude |
read:users | Lire les membres de l'équipe |
Convention de nommage :
<action>:<ressource> — l'action vient toujours en premier. Un scope write:* accorde implicitement le read:* correspondant, plus les opérations de création / modification / suppression. Les scopes webhook accordent en plus la permission legacy settings:* pour la rétro-compatibilité.
Principe du moindre privilège : N'accordez que les scopes dont votre intégration a réellement besoin. Vous pourrez toujours en ajouter plus tard.
Bonnes pratiques de sécurité
- N'exposez jamais les clés API dans du code client ou des dépôts publics
- Effectuez une rotation des clés API régulièrement (au moins tous les 90 jours)
- Utilisez des variables d'environnement pour stocker les clés, pas des chaînes en dur
- Utilisez le scope le plus restreint possible pour chaque clé API
- Surveillez l'utilisation de l'API dans votre tableau de bord pour détecter toute activité suspecte
- Révoquez immédiatement les clés compromises depuis Paramètres → Intégrations