Résoudre les problèmes de clés API
Causes et solutions des erreurs renvoyées lors d'un appel avec une clé sk_, ou lors de la vérification d'une clé wsk_ par votre wakapp.
This page has not been translated yet and is shown in French.
Cette page part de la réponse de l'API publique à un appel authentifié par clé sk_, puis des symptômes propres aux clés de votre wakapp.
Symptômes
- 401 Cle API utilisateur invalide ou expiree
- 401 Authentification requise
- 403 Droit applicatif requis
- 403 Niveau d'administration insuffisant
- La clé agit avec les droits d'un utilisateur
- Les données renvoyées ne sont pas celles attendues
- 400 Environment is deduced from the caller and cannot be provided
- 429 Too Many Requests
Clés de votre wakapp :
- L'introspection renvoie toujours
active: false - 401 sur l'API Wakastart avec une clé wsk_
- 403 API_KEY_CANNOT_MANAGE_KEYS
- 403 RIGHTS_EXCEED_CEILING
- 403 APP_SCOPE_MISMATCH ou APP_NOT_RESOLVED
- Une clé révoquée est encore acceptée par votre wakapp
- L'ancien secret ne fonctionne plus après une rotation
- 429 sur l'introspection
- 401 CONTEXT_INVALID ou 403 CONTEXT_REQUIRED
401 Cle API utilisateur invalide ou expiree
Cause : la clé est inconnue (faute de copie, espace en trop), révoquée, désactivée, expirée, ou utilisée depuis une adresse IP absente de sa liste autorisée.
Solution :
- Vérifiez que la valeur commence par
sk_et compte 43 caractères, sans espace ni retour à la ligne. - Vérifiez l'adresse IP de sortie réelle de votre serveur (passerelle NAT, proxy) et comparez-la à la liste autorisée. Les plages
/32,/8,/28et les adresses IPv6 ne sont pas reconnues : déclarez des adresses exactes ou des blocs/24ou/16. - Vérifiez la date d'expiration de la clé.
- Si rien ne l'explique, considérez la clé comme révoquée et demandez son remplacement au support.
401 Authentification requise
{
"statusCode": 401,
"message": "Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header)"
}Cause : la requête ne porte pas d'en-tête x-api-key, souvent parce qu'un proxy ou un client HTTP le retire, ou que le nom de l'en-tête est mal orthographié.
Solution : envoyez exactement x-api-key, et vérifiez avec curl -v que l'en-tête part bien.
403 Droit applicatif requis
{ "statusCode": 403, "message": "Droit applicatif requis : invitations.create" }Cause : le profil de la clé ne porte pas le droit exigé par l'opération.
Solution : demandez une nouvelle clé dont le profil porte ce droit (une clé ne se modifie pas), puis faites la rotation (voir Faire tourner une clé).
403 Niveau d'administration insuffisant
{ "statusCode": 403, "message": "Niveau d'administration insuffisant. Requis: CUSTOMER_ADMIN, Actuel: NONE" }Cause : l'opération exige un niveau minimal que la clé n'a pas. Une clé technique sans niveau fixé n'en a aucun.
Solution : demandez une clé du niveau requis.
La clé agit avec les droits d'un utilisateur
Cause : la requête porte aussi un en-tête Authorization. Dans ce cas, l'API utilise le jeton et ignore la clé.
Solution : retirez l'en-tête Authorization des appels authentifiés par clé.
Les données renvoyées ne sont pas celles attendues
Cause : la clé agit dans le périmètre de son client et de son environnement. Une liste d'utilisateurs ne contient que ceux du client de la clé, et une invitation est créée dans l'environnement de la clé.
Solution : utilisez une clé rattachée au bon client et au bon environnement. Les droits d'une clé se lisent dans la matrice profils × droits de l'environnement de la clé : une clé dev peut avoir moins, ou plus, de droits qu'une clé prod du même profil. Vérifiez la matrice de cet environnement dans la console.
400 Environment is deduced from the caller and cannot be provided
Cause : la requête porte un paramètre env, envType ou envs, dans l'URL ou dans le corps. L'environnement d'un appel par clé est toujours celui de la clé.
Solution : retirez ce paramètre. Pour agir dans un autre environnement, utilisez une clé de cet environnement.
429 Too Many Requests
Cause : la limite de débit par adresse IP est dépassée (10 requêtes par seconde, 100 par minute, 1 000 par heure).
Solution : étalez les appels, regroupez les lectures avec la pagination (limit jusqu'à 100) et réessayez avec un délai croissant.
L'introspection renvoie toujours active: false
Cause : la réponse négative est la même pour une clé inconnue, révoquée, expirée, suspendue, d'une autre application, d'un autre environnement, ou dont l'organisme n'a plus l'application. Le cas le plus fréquent est un écart d'environnement : une clé dev présentée à votre wakapp de production, ou une clé sk_ de votre wakapp d'un autre environnement que la clé du client.
Solution :
- Dans l'onglet Clés API de l'app, vérifiez le statut, l'application et l'environnement de la clé.
- Vérifiez que la clé
sk_de votre wakapp appartient au même environnement que la clé du client. - Vérifiez que le secret est transmis entier, sans le préfixe
Bearer.
401 sur l'API Wakastart avec une clé wsk_
Cause : une clé de votre wakapp a été envoyée directement à l'API publique Wakastart. Elle n'y a aucun droit.
Solution : vos clients appellent votre wakapp avec leur clé wsk_ ; votre wakapp appelle Wakastart avec sa propre clé sk_ (voir Agir sur Wakastart pour un client).
403 API_KEY_CANNOT_MANAGE_KEYS
Cause : une opération de gestion /api/app-keys a été appelée avec la clé sk_ de votre wakapp. Une clé ne gère jamais de clés.
Solution : appelez ces opérations avec le jeton de l'utilisateur connecté dans Authorization: Bearer (voir Proposer les clés dans votre wakapp).
403 RIGHTS_EXCEED_CEILING
{ "statusCode": 403, "message": "RIGHTS_EXCEED_CEILING", "error": "Forbidden", "details": { "missing": ["formations.delete"] } }Cause : un droit demandé dépasse les droits actuels de la personne qui agit, pour cette application et cet environnement. Dans la console, le message est « Vous ne détenez pas ces droits, vous ne pouvez pas les accorder ».
Solution : retirez les droits cités dans details.missing, ou faites créer la clé par une personne qui les détient.
403 APP_SCOPE_MISMATCH ou APP_NOT_RESOLVED
Cause : APP_SCOPE_MISMATCH, votre wakapp envoie appWid ou envType et la valeur diffère de celle du jeton de l'utilisateur. APP_NOT_RESOLVED, le jeton ne désigne aucune application cliente, par exemple un jeton émis pour la console Wakastart.
Solution : n'envoyez ni application ni environnement, et utilisez le jeton émis pour votre wakapp, dans l'environnement voulu.
Une clé révoquée est encore acceptée par votre wakapp
Cause : votre wakapp garde en cache les réponses positives de l'introspection.
Solution : supprimez ce cache. Seules les réponses négatives peuvent être gardées quelques secondes (voir Vérifier une clé de votre wakapp).
L'ancien secret ne fonctionne plus après une rotation
Cause : l'ancien secret reste valable 7 jours au plus, et jamais au-delà de l'échéance de la clé. Une seconde rotation pendant ce délai coupe immédiatement le secret qui était déjà en sursis.
Solution : transmettez au client le dernier secret affiché. Évitez d'enchaîner les rotations tant que le client n'a pas basculé.
429 sur l'introspection
Cause : votre wakapp dépasse la limite de 3 000 introspections ou de 600 demandes de contexte « utilisateur » par minute, pour son application et l'environnement de sa clé sk_.
Solution : attendez le nombre de secondes indiqué par l'en-tête Retry-After. Gardez quelques secondes les réponses négatives pour ne pas relayer un essai de secrets en masse, et limitez le débit de chaque client côté wakapp.
401 CONTEXT_INVALID ou 403 CONTEXT_REQUIRED
Cause : CONTEXT_INVALID, le jeton de contexte a expiré (plus de 60 secondes) ou a été émis pour une autre application ou un autre environnement. CONTEXT_REQUIRED, l'action est passée en mode required ou bound pour votre application et la requête ne porte pas de contexte.
Solution : obtenez le contexte pendant la requête du client et joignez-le aussitôt dans X-WakaStart-Context (voir Agir sur Wakastart pour un client).
Toujours bloqué ?
Rassemblez avant de contacter le support :
- le nom et les 10 premiers caractères de la clé, jamais la clé complète ;
- la méthode, le chemin et l'heure exacte de l'appel ;
- l'adresse IP de sortie de votre serveur ;
- la réponse complète de l'API.