Si vous utilisez la plateforme destinée aux développeurs, il est probable que vous ayez rencontré des erreurs 401 ou 403. Ces deux codes de statut expliquent un pourcentage important de demandes API ratées de la part des développeurs, surtout au début du cycle de vie d’une intégration.

Bien que ces deux erreurs soient liées au contrôle d’accès, elles échouent pour des raisons très différentes et nécessitent des approches de débogage différentes. Les traiter de façon interchangeable est souvent synonyme de perte de temps et d’échecs de demandes répétés.

Dans cet article, nous allons vous expliquer comment les erreurs 401 et 403 fonctionnent dans Zendesk, comment les diagnostiquer rapidement et comment les corriger à l’aide d’exemples pratiques et d’étapes de dépannage.

Ce que vous apprendrez

À la fin de cette publication, vous comprendrez :

  • La différence entre Non autorisé et 403 Interdit dans Zendesk
  • Comment effectuer une authentification correcte en utilisant les tokens API, les tokens d’accès OAuth et les JWT
  • Impact des étendues d’ OAuth sur l’autorisation
  • Comment diagnostiquer les en-têtes mal formés, les sous-domaines incorrects et les identifiants arrivés à expiration

 

Comprendre les paramètres 401 et 403

Bien que les deux codes se rapportent au contrôle d’accès, ils échouent à différentes étapes du traitement de la demande.

401 Unauthorized

Une réponse 401 signifie que l’API Zendesk n’a pas réussi à authentifier la demande. Zendesk n’a pas réussi à déterminer qui est l’appelant et n’essaie donc pas d’évaluer les permissions ou la logique de gestion.

Les causes courantes incluent :

  • En-têtes d’autorisation manquants ou mal formés
  • Encodage Base64 incorrect pour l’authentification de base
  • Formatage des e-mails et des tokens incorrect
  • Tokens API révoqués ou arrivés à expiration
  • Utilisation des tokens OAuth dans un en-tête d’authentification de base
  • JWT non valides ou arrivés à expiration pour la messagerie

Si vous recevez une erreur 401, concentrez-vous d’abord sur la façon dont la demande est authentifiée, pas sur ce qu’elle essaie de faire.

403 Interdit

Une réponse 403 signifie que la demande a été authentifiée, mais que l’identité authentifiée n’a pas la permission d’effectuer l’action demandée.

Les causes typiques incluent :

  • Tokens OAuth manquant dans les étendues d’autorisation requises
  • Utilisation des identifiants de l’utilisateur final pour appeler les points de terminaison réservés aux agents
  • Tentative d’accès à des ressources appartenant à une autre marque
  • Restrictions IP activées pour le compte
  • Comptes d’agents suspendus ou rétrogradés

Si vous recevez une erreur 403, l’authentification fonctionne correctement. Le problème est l’autorisation.

 

Un workflow de diagnostic rapide

Lors du débogage des problèmes d’accès, la méthode la plus rapide consiste à identifier le problème étape par étape.

Commencez par tester votre requête avec curl. Si la demande curl échoue, le problème provient probablement des identifiants ou de la configuration du compte, et non du code de votre application.

Ensuite, vérifiez que vous appelez le bon sous-domaine Zendesk. Les identifiants sont limités à un environnement spécifique, et les tokens de sandbox et de production ne sont pas interchangeables.

Ensuite, vérifiez que vous utilisez la méthode d’authentification correcte. Le mélange authentification de base, OAuth et JWT est une source d’échec courante.

Vérifiez le rôle de l’utilisateur authentifié. De nombreux points de terminaison nécessitent des permissions d’agent ou d’administrateur, même si l’authentification réussit.

Si vous utilisez OAuth, vérifiez que le token inclut les étendues d’autorisation requises par le point de terminaison.

Enfin, considérez l’endroit vers lequel la demande est en cours. Les demandes provenant du navigateur sont souvent bloquées par les politiques CORS (politique de partage des ressources multinavigateur) quand vous utilisez l’authentification de base avec token API ou d’autres workflows côté client non pris en charge. Si vous avez besoin d’appeler l’API à partir d’un navigateur, utilisez un flux OAuth qui prend en charge CORS ou routez les demandes via un service backend ou une application Zendesk en utilisant le client ZAF . Pour en savoir plus au sujet des demandes CORS, consultez Envoi de demandes CORS côté client à l’API de gestion des tickets. 

 

Authentification correcte

L’authentification a lieu avant la vérification de la permission ou de la logique de gestion. Si l’authentification échoue, Zendesk ne peut pas associer la demande à un utilisateur ou une intégration et renvoie une erreur 401.

Zendesk prend en charge plusieurs méthodes d’authentification, chacune avec des exigences de formatage strictes.

Authentification par token API

Les tokens API utilisent l’authentification de base, où le nom d’utilisateur inclut le suffixe /token.

Le format correct est :

curl -v \
  -u "agent@example.com/token:YOUR_API_TOKEN" \
  "https://your_subdomain.zendesk.com/api/v2/tickets.json"

Une erreur courante qui provoque une erreur 401 est d’omettre le suffixe /token  :

emailAddress:APITOKEN

Dans Node.js, un exemple fonctionne comme suit :

import fetch from "node-fetch";
import btoa from "btoa";

const subdomain = "your_subdomain";
const email = "agent@example.com";
const token = process.env.API_TOKEN;

const response = await fetch(
  `https://${subdomain}.zendesk.com/api/v2/users/me.json`,
  {
    headers: {
      'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.status, await response.text());

 

Authentification OAuth

Les tokens d’accès OAuth sont couramment utilisés pour les intégrations qui nécessitent des identifiants de longue durée ou un contrôle de permission détaillé. Les tokens OAuth doivent être envoyés en utilisant le schéma d’authentification du porteur . Le format d’en-tête correct est :

Authorization: Bearer ACCESS_TOKEN

Exemple de demande utilisant curl :

curl \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://your_subdomain.zendesk.com/api/v2/users/me.json"

Dans Node.js, un exemple fonctionne comme suit :

import fetch from "node-fetch";

const subdomain = process.env.SUBDOMAIN;
const token = process.env.OAUTH_TOKEN;

const url = `https://${subdomain}.zendesk.com/api/v2/users/me.json`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`
  }
});

console.log(response.status, await response.text());

Une cause commune d’erreurs de type 401 Unauthorized lors de l’utilisation OAuth est l’envoi d’un token d’accès valide avec le mauvais schéma d’authentification. Dans ce cas, Zendesk ne parvient pas à authentifier la demande et renvoie un 401 avant d’évaluer les portées ou les permissions.

Les tokens OAuth introduisent également le concept de portées, qui définissent explicitement les actions que le token est autorisé à effectuer. Un token peut s’authentifier, mais renvoyer une réponse 403 Interdit s’il n’a pas les portées requises par le point de terminaison appelé.

Par exemple, un token avec tickets:read peut récupérer les données de ticket, mais ne peut pas créer ou mettre à jour des tickets. Si vous essayez une opération d’écriture sans la portée appropriée, vous recevrez systématiquement une erreur 403. 

403: You do not have access to this resource

Si cela se produit, l’authentification fonctionne normalement, mais le token doit être recréé avec les bonnes valeurs. Pour en savoir plus au sujet des portées, consultez l’article sur les tokens OAuth pour les types d’octroi.

 

Authentification JWT pour la messagerie

Lors de l’implémentation de la messagerie Zendesk dans les applications Web ou mobiles, l’authentification JWT est utilisée pour identifier les utilisateurs finaux de façon sécurisée. Dans ce modèle, c’est votre backend qui est responsable de la génération et de la signature d’un Token Web JSON (JWT) en utilisant le secret configuré dans le Centre d’administration. Zendesk valide le token avant d’autoriser l’association de la session Messagerie à un utilisateur.

Contrairement aux tokens API ou à OAuth, les JWT de messagerie nécessitent des informations de revendication et d’en-tête spécifiques qui permettent à Zendesk de résoudre correctement l’identité de l’utilisateur.

Au minimum, un JWT de messagerie doit inclure :

  • child – L’ID de la clé dans le Centre d’administration Zendesk. Cela doit être inclus dans l'en-tête JWT, pas dans la charge.
  • external_id – Identifiant unique de l’utilisateur. Zendesk utilise cette valeur comme clé principale lors de la mise en correspondance ou de la création d’enregistrements d’utilisateur.
  • scope – doit être configuré sur « user » pour indiquer que le token est conçu pour l’authentification des utilisateurs finaux dans la messagerie.

Des revendications supplémentaires comme name, emailet email_verified sont facultatives et peuvent être incluses pour remplir les détails d’utilisateur dans l’interface d’agent ou assistance la correspondance d’identité basée sur l’adresse e-mail.


Exemple de générateur JWT Node.js : 

import jwt from "jsonwebtoken";
const payload = {
  scope: "user",
  external_id: "user_12345",
  name: "Jane Doe",
  exp: Math.floor(Date.now() / 1000) + (5 * 60)
};

const token = jwt.sign(payload, process.env.ZENDESK_JWT_SECRET, {
	keyid: process.env.ZENDESK_KEYID,
});

console.log(token);

Si des revendications obligatoires comme external_id ou scope sont manquantes, ou si le token est signé avec le mauvais secret, Zendesk renvoie une réponse 401 Unauthorized.


Les causes courantes d’erreurs 401 liées à JWT incluent :

  • Utilisation d’un secret JWT du mauvais environnement (sandbox vs production)
  • Envoi d’un token expiré ou avec des revendications temporelles non valides
  • En excluant les revendications obligatoires comme external_id ou scope 
  • Signature du token avec un secret incorrect ou modifié
  • Envoi d’un JWT mal formé ou codé de façon incorrecte

Quand vous déboguez des problèmes d’authentification dans la messagerie, commencez par vérifier que le token est signé avec le bon secret et inclut les revendications requises. Si l’authentification réussit, mais si le comportement de l’identité de l’utilisateur est inattendu, vérifiez les valeurs utilisées pour external_id et tous les champs d’identité facultatifs pour vérifier qu’elles sont stables et cohérentes d’une session à l’autre. Pour en savoir plus, consultez Authentification des utilisateurs dans votre application.
 

Causes courantes des erreurs 401

Une réponse 401 signifie que Zendesk n’a pas réussi à authentifier la demande et n’a pas réussi à déterminer l’identité de l’appelant.

Cela est souvent dû à des en-têtes d’autorisation mal construits, des tokens désactivés ou des erreurs de correspondance de l’environnement.

Les en-têtes d’authentification élémentaire doivent être formatés comme suit, ou l’équivalent :

headers: {
      'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
      'Content-Type': 'application/json'
}

Les caractères inattendus, les espaces blancs ou les problèmes de codage sont souvent la cause d’échecs silencieux.

Enfin, n’oubliez pas que l’API REST Zendesk ne prend pas en assistance l’authentification d’origine du navigateur. Les demandes JavaScript côté client échoueront à cause de CORS, de cookies de session manquants et de workflows d’authentification non pris en charge. Utilisez un service backend ou une application Zendesk créée avec le client ZAF .

 

Causes courantes des erreurs 403

Une réponse 403 indique que Zendesk a authentifié la demande, mais a refusé l’accès à cause de règles de permissions.

La cause la plus courante est l’absence de champs d’application OAuth . Par exemple, un token avec ticket:read peut récupérer les tickets, mais ne peut pas les créer ni les mettre à jour. Les tentatives d’écriture renvoient systématiquement une erreur 403.

Les étendues d’autorisation OAuth ne peuvent pas être modifiées après la création d’un token. Si les champs d’application sont incorrects, un nouveau token doit être généré.

Une autre source courante de confusion est la tentative d’appel de points de terminaison réservés aux agents à l’aide des identifiants de l’utilisateur final. Les tokens OAuth des utilisateurs finaux peuvent fonctionner pour /users/me, mais renverront 403 quand ils appellent des points de terminaison restreints comme des tickets, des vues ou des champs de ticket.

Les autres causes courantes de ce problème incluent les tokens révoqués, les restrictions de la liste autorisée d’adresses IP et les limitations de l’accès pour plusieurs marques. Dans ce cas, la demande est refusée soit parce que les identifiants ne sont plus actifs, soit parce que l’utilisateur ne satisfait pas à certains critères d’accès.

 

Une approche de dépannage détaillée

1. Valider les identifiants séparément En cas de doute, commencez par supprimer le code de votre application de l’équation. Validez vos identifiants avec curl :

curl -v \
  -u "email/token:token" \
  "https://your_subdomain.zendesk.com/api/v2/users/me.json"
  • Si cela ne marche pas : Il s’agit probablement d’un problème lié à un identifiant ou à un compte.
  • Si cela réussit : Les identifiants sont valides. Le problème provient de la logique ou de l'environnement de l'application. Passez à l’étape 2.

2. Vérifiez les limites de CORS : Si la commande curl fonctionne, mais que votre application côté client échoue, il est probable que vous atteigniez des restrictions CORS.

Ouvrez la console de développement de votre navigateur et recherchez l’erreur. Si vous voyez une erreur 401/403 accompagnée d’un message de la console concernant Access-Control-Allow-Origin, le navigateur bloque la demande avant que Zendesk ne puisse la traiter.

3. Inspecter les en-têtes de la demande brute Si vous exécutez du code côté serveur (Node.js, Python, PHP, etc.) et rencontrez toujours des problèmes : .

  • Consigner l’en-tête d’autorisation : Imprimez la chaîne exacte qu’envoie votre application. Vérifiez qu’il n’y a pas d’espaces blancs masqués ou de préfixes incorrects (par ex. pour vous assurer que Basic et Bearer sont utilisés correctement).
  • Vérifier Environnement : Vérifiez que votre application cible le bon sous-domaine. Il n’est pas rare de cibler accidentellement une URL de sandbox avec des identifiants de production, ou vice versa.

4. Vérifier les portées et les revendications Si l’authentification réussit, mais que vous recevez un 403 Interdit, il est possible que votre token ne dispose pas des autorisations nécessaires.

  • Pour OAuth: Vérifiez vos étendues d’autorisation actuelles en appelant le point de terminaison /api/v2/oauth/tokens/current . Vérifiez que le token a la portée requise pour la ressource à laquelle vous essayez d’accéder.

  • Pour la messagerie/JWT : Revalidez votre charge JWT. Vérifiez que l’enfant (ID de la clé) correspond à votre configuration Zendesk et que le secret de signature utilisé pour générer le token est correct.

     

Dernières réflexions

La plupart des erreurs 401 et 403 sur la plateforme des développeurs Zendesk proviennent de quelques erreurs de configuration prévisibles. Une fois que vous avez clairement distinct les échecs d’authentification des échecs d’autorisation, le débogage devient beaucoup plus rapide et plus fiable.

En vérifiant les identifiants le plus tôt possible, en confirmant les portées et les rôles, et en suivant une approche de diagnostic structurée, vous pouvez résoudre ces problèmes rapidement et éviter qu’ils ne se reproduisent.

Pour en savoir plus, consultez la documentation Zendesk sur l’accès par token API, l’authentification OAuth, leframework des applications Zendesket l’authentification JWT pour la messagerie.

Traduction - exonération : cet article a été traduit par un logiciel de traduction automatisée pour permettre une compréhension élémentaire de son contenu. Des efforts raisonnables ont été faits pour fournir une traduction correcte, mais Zendesk ne garantit pas l’exactitude de la traduction.

Si vous avez des questions quant à l’exactitude des informations contenues dans l’article traduit, consultez la version anglaise de l’article, qui représente la version officielle.

Réalisé par Zendesk