API keys et accès

Les échecs d'authentification sont les plus faciles à diagnostiquer, car l'API renvoie un code différent pour chaque cause. Ces codes ne correspondent pas toujours aux attentes : la validation renvoie 422, une mauvaise classe de clé renvoie 406 et le code 409 n'est jamais utilisé.

Erreur 401 Invalid or revoked API credentials

La clé n'est pas reconnue comme un identifiant utilisable. Il existe quatre causes. La vérification interroge la base de données à chaque requête. Une clé révoquée à l'instant cesse donc immédiatement de fonctionner.

Envoyez-la dans Authorization sans préfixe Bearer. L'API considère la valeur de l'en-tête comme la clé elle-même. Ajouter Bearer fait échouer la recherche comme toute faute de frappe.

curl https://api.wajub.com/payments \
  -H "Authorization: sk_test.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…"

Erreur 403 Security Alert: You are trying to use a Private Key from a browser dans le navigateur

Une clé sk. est arrivée avec un en-tête Origin ou Referer, envoyé uniquement par un navigateur. Wajub refuse l'appel et envoie un e-mail au propriétaire de la clé, dans la limite d'une alerte par clé et par heure.

Deux actions sont nécessaires. Déplacez l'appel vers votre serveur et considérez la clé comme divulguée. Elle se trouvait dans une application téléchargée par quelqu'un. Créez une clé de remplacement, déployez-la, puis supprimez l'ancienne. Bonnes pratiques de sécurité présente la procédure qui évite une interruption.

Erreur 403 IP address not allowed for this API key liée à l'adresse IP

La clé possède une liste d'IP autorisées et l'appelant n'y figure pas. Cette liste s'applique à tous les types de clés, y compris les clés publiques. Elle accepte des adresses IPv4 ou IPv6 exactes et des plages CIDR des deux familles. Une liste vide ne pose aucune restriction.

La cause habituelle est un déploiement qui modifie votre adresse de sortie ou un job exécuté depuis une machine non ajoutée. Comparez l'IP réelle de l'appelant à la liste de la clé.

Erreur 403 This API key does not have permission to read payment liée au scope

Une clé restreinte ne possède pas le scope exigé par la route. Les scopes suivent le format {resource}.{read|write}. Le verbe détermine la partie nécessaire : GET, HEAD et OPTIONS exigent read, les autres verbes exigent write.

Cette erreur possède une seconde forme importante.

Cette réponse ne signale pas un scope manquant. Une clé restreinte fonctionne comme une liste d'autorisations, pas comme un filtre. Si une route ne correspond à aucune ressource avec des scopes, aucune clé restreinte ne peut l'atteindre, quelles que soient ses autorisations. Quatre chemins font exception, car ils ne contiennent aucune donnée sensible : /channels, /countries, /currencies et la racine de l'API.

Deux ressources sont accessibles en lecture seule : balance et account. Une clé restreinte ne peut jamais les modifier et ne peut donc pas créer de connexion Sync. Utilisez pour cela une clé privée sur votre serveur.

Erreur 406 Private Key Required pour une clé publique

La route exige une clé privée, mais vous avez envoyé une clé publique. Cette règle concerne /balance, /transfers, /refunds, /disputes et /beneficiaries.

/payments et /accounts ne figurent pas dans cette liste. Une clé publique peut créer un paiement et une connexion Sync. Le fait qu'un appel provenant d'une clé publique soit accepté ne signifie pas qu'il doit être effectué dans un navigateur.

« Je reçois une erreur CORS »

Ce n'est presque certainement pas le cas. Toutes les réponses de l'API, y compris les erreurs, contiennent Access-Control-Allow-Origin: *. Les requêtes préliminaires OPTIONS répondent avec 204, les méthodes et les en-têtes autorisés. Wajub ne produit pas d'erreurs CORS.

Le navigateur signale probablement l'une des situations suivantes comme une requête échouée.

Vérifiez surtout la dernière ligne dans l'onglet réseau. La requête préliminaire autorise Content-Type, Authorization, X-Requested-With, Accept, Origin, Idempotency-Key et X-Link-View-Token. Tout autre en-tête fait échouer cette requête. Le navigateur signale alors une erreur CORS pour un appel que l'API n'a jamais examiné.

Réponse 404 pour un identifiant qui existe

La sandbox et le mode live utilisent des bases distinctes, sélectionnées par le préfixe de votre clé avant la première requête. Un identifiant d'un environnement n'existe réellement pas dans l'autre. La réponse est donc 404, pas une erreur d'autorisation. Les identifiants de la sandbox contiennent test_ après leur préfixe, ce qui permet de les reconnaître immédiatement.

La même règle s'applique entre les équipes. Un identifiant ne peut pas être résolu hors de l'équipe qui le possède. La réponse 404 est volontaire, car 403 confirmerait l'existence de l'objet.

Réponse 422 avec errors.idempotency_key

Vous avez réutilisé une Idempotency-Key avec un payload différent. Vous avez soit modifié un montant sans changer la clé, soit réutilisé une clé qui devait être renouvelée. Le problème n'est pas temporaire et une nouvelle tentative produit la même réponse.

Le format de la clé est aussi validé avant tout autre contrôle : A-Z, a-z, 0-9 et . _ : -, de 1 à 128 caractères. Un numéro de commande comme #4172 ou un UUID entre accolades est refusé à cause de son format.