App Store Connect API 401 : comment corriger le JWT en 2026 ?

Apple précise que le JWT utilisé par l’App Store Connect API ne peut pas rester valide indéfiniment : sa durée maximale est limitée à 20 minutes selon la documentation officielle de génération des jetons. Ce détail suffit à orienter le diagnostic : ne révoquez pas immédiatement toutes vos clés.

Symptôme → solution la plus rapide : si votre script local génère un JWT mais que le Runner distant renvoie 401 NOT_AUTHORIZED, confirmez d’abord l’API appelée, puis contrôlez la provenance de la clé, les champs du JWT, l’horloge, les rôles et l’injection des secrets. Si la même requête minimale échoue encore après cette vérification, transmettez à Apple l’identifiant de requête et un diagnostic désensibilisé plutôt que de renouveler les clés sans preuve.

Cet article s’adresse à vous si vous utilisez fastlane pour envoyer une version à TestFlight, si un pipeline fonctionnait avant son déplacement vers un Mac distant, ou si vous signez vous-même les JWT destinés à l’App Store Connect API. Il ne s’agit pas d’un tutoriel général de compilation ou de signature : l’objectif est d’isoler une erreur d’authentification.

Commencez par identifier exactement la requête qui échoue

Un JWT correctement formé ne prouve pas que la clé, l’API et l’opération correspondent. Dans un cas typique, un script local affiche un jeton signé sans erreur, tandis que le Runner distant reçoit 401 NOT_AUTHORIZED au moment d’interroger une ressource ou de lancer l’automatisation d’envoi.

Avant de modifier un secret, conservez les éléments suivants dans un journal désensibilisé :

• l’adresse complète du point d’accès, sans inclure de jeton ;
• le statut HTTP et le code d’erreur renvoyé par Apple ;
• l’identifiant de requête transmis dans la réponse ;
• l’outil déclencheur : script maison, fastlane, Transporter ou autre action ;
• l’étape exacte : lecture d’une ressource, création d’une opération ou transfert d’un paquet ;
• l’environnement : terminal local, session SSH ou tâche CI sur le Mac distant.

L’App Store Connect API, l’App Store Server API, Transporter et une action fastlane ne sont pas des synonymes. Une clé .p8 peut donner une impression trompeuse de compatibilité parce que le fichier possède le même format cryptographique, alors que son portail de création, son périmètre et son point d’accès diffèrent.

La documentation Apple sur les réponses d’erreur de l’App Store Connect API doit servir de référence pour distinguer une authentification refusée d’une ressource interdite ou absente. Ne déduisez pas l’usage d’une clé à partir de son nom de fichier, de son emplacement ou de l’extension .p8.

Une méthode d’isolement en trois entrées

Exécutez la même requête minimale, avec les mêmes paramètres non sensibles, depuis trois contextes :

Cette comparaison ne doit pas afficher la clé privée, le JWT complet, l’Issuer ID ou le contenu d’une variable secrète. Utilisez des valeurs masquées telles que <KEY_ID>, <ISSUER_ID>, <APP_ID> et <PRIVATE_KEY_PATH>.

Si le terminal local et SSH réussissent, mais que le Runner échoue, la cause est probablement dans l’environnement d’exécution ou la transmission des secrets. Si les trois entrées échouent avec le même identifiant de requête ou le même type d’erreur, revenez à la clé, au JWT et aux droits avant d’accuser le réseau.

La clé et le JWT doivent correspondre à l’API appelée

Une clé App Store Connect peut-elle remplacer une clé In-App Purchase ?

Non, vous ne devez pas mélanger ces clés simplement parce qu’elles utilisent toutes deux un fichier .p8. Vérifiez l’écran Apple depuis lequel la clé a été créée, le type de service concerné et le point d’accès ciblé. La page Apple consacrée à l’App Store Connect API est la référence pour confirmer l’origine de la clé et son usage attendu.

Contrôlez ensuite la cohérence entre :

• le Key ID utilisé dans l’en-tête du JWT ;
• l’Issuer ID fourni par l’espace App Store Connect concerné ;
• la clé privée réellement chargée par le script ;
• l’API et l’adresse appelées ;
• le rôle attribué à la clé ou au compte qui l’a créée.

Une erreur fréquente consiste à conserver dans le Runner un ancien fichier portant un nom plausible, puis à mettre à jour uniquement le Key ID. Le JWT peut alors être signé avec une clé privée différente de celle qui correspond à cet identifiant. La signature est techniquement produite, mais Apple ne peut pas l’associer au bon identifiant public.

Les champs JWT à contrôler dans le bon ordre

Traitez le jeton en trois couches : l’en-tête, la charge utile et la signature.

Dans l’en-tête, vérifiez au minimum :

• alg, qui doit correspondre à l’algorithme attendu ;
• kid, qui doit identifier la clé publique associée à la clé privée ;
• la signature produite avec la bonne clé privée.

Pour l’App Store Connect API, Apple documente l’utilisation de ES256. La documentation officielle sur la génération des tokens doit être suivie pour les noms de champs et les contraintes temporelles ; évitez de reprendre un exemple trouvé dans un autre contexte Apple.

Dans la charge utile, contrôlez :

• iss, qui doit correspondre à l’émetteur attendu ;
• iat, l’instant d’émission ;
• exp, l’expiration ;
• aud, l’audience prévue ;
• toute différence entre les valeurs injectées localement et celles du Runner.

La vérification locale du décodage ou de la signature ne répond qu’à une question cryptographique : « le jeton est-il lisible et signé avec cette clé ? » Elle ne confirme ni le type de clé, ni l’audience, ni le rôle, ni l’accès à la ressource demandée. C’est pourquoi un JWT localement valide peut toujours être rejeté par Apple.

L’horloge du Mac distant peut invalider un jeton correct

Comparez l’heure du Mac distant à une source de temps fiable, surtout après une sortie de veille, une restauration d’instantané ou une modification manuelle de l’horloge. Un décalage modifie la relation entre iat et exp, et peut rendre le jeton inutilisable alors que le code de signature n’a pas changé.

Ne corrigez pas ce problème en augmentant arbitrairement la durée du jeton. La limite documentée par Apple doit rester votre référence. Si l’horloge est instable, corrigez le service de synchronisation du système, relancez une génération propre et vérifiez que le Runner utilise bien l’heure du système au moment de l’appel.

Les droits peuvent-ils expliquer un 401 NOT_AUTHORIZED ?

Distinguez authentification et autorisation

Un 401 attire naturellement l’attention sur le JWT, mais une investigation sérieuse doit aussi vérifier le compte, la clé et le périmètre de l’opération. Ne concluez pas automatiquement qu’Apple rencontre une panne générale : les discussions de développeurs peuvent signaler des symptômes récurrents, mais elles ne constituent pas une confirmation officielle d’un incident systémique.

Examinez séparément :

1. l’identité reconnue par Apple ;
2. le rôle associé à la clé ;
3. l’accès à l’application ou aux ressources visées ;
4. l’état du contrat et de l’équipe ;
5. le type d’opération demandé.

La matrice officielle des rôles et permissions vous aide à vérifier si l’action visée entre réellement dans le périmètre du rôle. Un compte peut être valide pour lire une ressource, mais ne pas disposer de l’autorisation nécessaire pour une opération différente.

Commencez par une requête de lecture minimale autorisée. Elle doit utiliser la même clé, le même Issuer ID, le même aud et le même environnement que l’automatisation réelle. Si cette requête échoue déjà, ne passez pas directement à l’analyse du paquet ou de la signature de code. Si elle réussit, mais que l’opération TestFlight échoue, la panne se situe probablement dans le périmètre de l’action, dans fastlane ou dans une étape distincte du transfert.

fastlane peut lire autre chose que ce que vous pensez

La documentation fastlane consacrée à l’App Store Connect API indique les paramètres utilisés pour l’authentification par clé. Dans votre configuration, comparez précisément :

• key_id ;
• issuer_id ;
• key_filepath ;
• key_content ;
• les variables d’environnement consommées par le processus ;
• le répertoire depuis lequel la tâche est lancée.

Une session interactive peut charger un fichier de profil contenant des variables que le Runner CI ne connaît pas. À l’inverse, un Runner peut recevoir une valeur encodée en Base64 alors que fastlane attend le contenu PEM avec ses retours à la ligne. Un chemin relatif peut également fonctionner dans votre terminal, puis pointer vers un emplacement vide lorsque la tâche démarre dans un autre répertoire.

Testez séparément les trois modes d’exécution :

• dans le terminal local, avec une sortie limitée aux identifiants masqués ;
• en SSH, sans supposer que l’environnement du terminal est identique ;
• dans la tâche CI, avec un affichage contrôlé de la présence, de la longueur et du format général du secret, jamais de sa valeur.

Les secrets d’API, les certificats de signature et les profils de provisioning répondent à des besoins différents. Ne placez pas la clé privée de l’API dans le dépôt, dans un artefact de compilation, dans les logs ou dans l’archive destinée à TestFlight.

Checklist de réparation et d’acceptation

Utilisez cette liste dans l’ordre. Cochez chaque élément uniquement après avoir obtenu une preuve exploitable.

• [ ] Identifier l’adresse appelée et confirmer qu’il s’agit bien de l’App Store Connect API, et non d’un autre service Apple.
• [ ] Conserver le statut HTTP, le code d’erreur, l’identifiant de requête et l’outil déclencheur.
• [ ] Vérifier dans le portail Apple l’origine exacte de la clé et son périmètre.
• [ ] Comparer le Key ID, l’Issuer ID et la clé privée réellement chargée.
• [ ] Contrôler alg, kid, iss, iat, exp et aud sans publier le JWT complet.
• [ ] Comparer l’horloge du Mac local, de la session SSH et du Runner distant.
• [ ] Vérifier le rôle, l’accès à l’application et l’état de l’équipe.
• [ ] Exécuter une requête de lecture minimale avec la même configuration.
• [ ] Reproduire l’appel depuis le terminal, SSH et le Runner en conservant les mêmes valeurs masquées.
• [ ] Tester ensuite l’action fastlane ou l’envoi TestFlight réel.
• [ ] Documenter l’étape qui réussit et celle qui échoue, au lieu de noter seulement « JWT généré ».
• [ ] Ne révoquer une clé qu’après avoir préparé une clé de remplacement, validé son usage et défini une possibilité de retour arrière.

La révocation immédiate est risquée : elle peut interrompre plusieurs pipelines qui utilisent la même clé, même si un seul Runner est défaillant. Créez ou sélectionnez une solution de remplacement uniquement lorsque vous savez quelle intégration sera affectée, puis testez-la avec la requête minimale avant de retirer l’ancienne.

Quand solliciter Apple

Si une clé issue du bon portail, un JWT conforme, une horloge correcte et un rôle adapté produisent encore un échec sur la requête minimale, arrêtez les rotations répétées. Préparez un dossier sans secret contenant :

• l’identifiant de requête ;
• la date et l’heure de l’appel ;
• le point d’accès concerné ;
• le code d’erreur ;
• le contexte d’exécution ;
• les champs non sensibles vérifiés ;
• la distinction entre l’appel local et l’appel distant.

Ne transmettez ni clé privée, ni JWT complet, ni jeton de session, ni contenu brut des variables d’environnement. Ce dossier permet de demander une analyse sans transformer un incident d’authentification en fuite de credentials.

Stabiliser le Mac distant après la correction

Une correction ponctuelle ne suffit pas si le pipeline doit rester disponible pour des envois TestFlight, des builds audio ou vidéo, ou des applications macOS distribuées régulièrement. Le Mac distant doit conserver un environnement reproductible : répertoire de travail explicite, variables injectées au niveau du Runner, journaux filtrés et accès SSH contrôlé.

Si vous comparez les options d’hébergement, consultez la page des cas d’usage Mac distant de KVMFLUX pour évaluer si votre besoin porte sur un test ponctuel, une tâche de publication ou une machine maintenue dans la durée. Pour un pipeline de démonstration ou une migration progressive, vous pouvez aussi comparer les formules disponibles sur la page de location Mac de KVMFLUX, sans confondre la disponibilité d’une machine avec la conformité de vos secrets.

L’ordre de validation reste le même après migration :

1. ouvrir une session contrôlée et confirmer le contexte système ;
2. injecter les secrets sans les écrire dans le dépôt ;
3. générer un JWT temporaire ;
4. exécuter la requête de lecture minimale ;
5. lancer l’action fastlane réelle ;
6. vérifier le résultat dans TestFlight ou dans la ressource attendue ;
7. conserver uniquement les journaux nécessaires au diagnostic.

Si votre solution actuelle repose sur un poste personnel, elle peut échouer lorsque l’ordinateur est éteint, lorsqu’une session graphique manque ou lorsque les variables d’environnement diffèrent entre l’utilisateur et le service CI. Un serveur cloud générique peut, de son côté, ne pas fournir le macOS réel nécessaire à votre chaîne Xcode et à vos outils Apple. Dans ces deux cas, vous payez soit par interruptions et interventions manuelles, soit par une couche de configuration qui éloigne le diagnostic de la machine réellement utilisée.

Un Mac distant loué chez KVMFLUX est donc à envisager lorsque vous avez besoin d’un environnement macOS conservé pour les secrets, les journaux et le Runner, tout en gardant la possibilité de commencer par une période courte pour valider votre processus. Faites d’abord réussir le vrai flux d’envoi avec vos propres identifiants, puis décidez si une location à la semaine suffit pour un test ou si une formule mensuelle est plus cohérente avec une publication récurrente.