Si vous utilisez la plateforme des développeurs Zendesk, vous avez probablement rencontré des erreurs 401 ou 403. Ces codes de statut sont à l’origine de nombreux échecs de demandes d’API de la part des développeurs, surtout au début du cycle de vie d’une intégration.

Bien que les deux erreurs concernent le contrôle d’accès, elles échouent pour des raisons différentes et nécessitent des approches différentes. Si vous les traitez comme interchangeables, vous risquez souvent de perdre du temps et de produire plusieurs échecs.

Ce que vous apprendrez

À la fin de cet article, vous comprendrez :

  • La différence entre les erreurs 401 Non autorisé et 403 Interdit dans Zendesk
  • Comment diagnostiquer les erreurs rapidement
  • Comment s’authentifier correctement avec les tokens API, les tokens d’accès OAuth et les JWT (tokens Web JSON)
  • Impact des portées OAuth sur l'autorisation
  • Comment diagnostiquer les en-têtes mal formés, les sous-domaines incorrects et les identifiants expirés
  • Comment corriger les erreurs en toute confiance grâce à des exemples pratiques et des étapes de dépannage

Différence entre les erreurs 401 et 403

Les deux codes de statut concernent le contrôle d’accès, mais ils échouent à différentes étapes du processus de demande.

401 Unauthorized

Une réponse 401 signifie que l’API Zendesk ne peut pas authentifier la demande. Zendesk ne peut pas identifier l’appelant et n’évalue donc pas les permissions ni la logique commerciale.

Les causes courantes incluent :

  • En-têtes d’autorisation absents ou mal formés
  • Encodage Base64 incorrect pour l’authentification de base
  • Format d’e-mail et de token incorrect
  • Tokens API expirés ou révoqués
  • Tokens OAuth dans un en-tête d'authentification Basic
  • JWT non valides ou expirés pour la messagerie

Si vous recevez une erreur 401, concentrez-vous sur la façon dont la demande s’authentifie, pas sur ce que la demande essaie de faire.

403 Interdit

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

Les causes typiques incluent :

  • Tokens OAuth sans portée requise
  • Identifiants des utilisateurs finaux pour les points de terminaison réservés aux agents
  • Accès aux ressources appartenant à une autre marque
  • Règles de la liste autorisée IP du compte
  • Comptes d’agent suspendus ou rétrogradés

Si vous recevez une erreur 403, l’authentification réussit. Le problème est l’autorisation.

Un workflow de diagnostic rapide

Quand vous déboguez des problèmes d’accès, la façon la plus rapide de procéder est d’isoler le problème étape par étape.

  1. Commencez par un test curl. Si la demande curl échoue, le problème concerne probablement les identifiants ou la configuration du compte, pas le code de votre application
  2. Confirmez que vous appelez le bon sous-domaine Zendesk. Les identifiants s'étendent à un environnement spécifique, et les tokens sandbox et de production ne s'interchangent pas.
  3. Vérifiez que vous utilisez la bonne méthode d’authentification. Les mélanges entre Basic Auth, OAuth et JWT provoquent souvent des échecs.
  4. 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
  5. Si vous utilisez OAuth, confirmez que le token inclut les portées que nécessite le point de terminaison
  6. Enfin, réfléchissez à l’endroit où s’exécute la demande. Les demandes d’origine du navigateur échouent souvent à cause des politiques CORS (Cross-Origin Resource Sharing) quand vous utilisez l’authentification Basic par token API ou d’autres workflows côté client non pris en charge. Si vous devez appeler l'API à partir d'un navigateur, utilisez un workflow OAuth qui prend CORS en charge, routez les demandes via un service backend ou utilisez une application Zendesk avec 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.

Comment s’authentifier correctement

L’authentification s’exécute avant toute vérification de permission ou de logique commerciale. 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 règles de format strictes.

Authentification par token API

Les tokens API utilisent l’authentification de base et le nom d’utilisateur doit inclure le suffixe /token.

Le format correct est :

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

Une erreur courante qui renvoie une erreur 401 est l’omission du suffixe /token :

emailAddress:APITOKEN

Un exemple Node.js :

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 intégrations qui ont besoin d'identifiants de longue durée ou d'un contrôle fin des permissions utilisent souvent OAuth. Envoyez des tokens d'accès OAuth avec le schéma Bearer. Utilisez cet en-tête :

Authorization: Bearer ACCESS_TOKEN

Exemple de demande avec curl :

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

Un exemple Node.js :

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 fréquente de 401 Non autorisé avec OAuth est un token d'accès valide envoyé avec le mauvais schéma. Dans ce cas, Zendesk ne peut pas authentifier la demande et renvoie un 401 avant d’évaluer les portées ou les permissions.

Les tokens OAuth utilisent aussi des portées qui définissent les actions autorisées. Un token peut s’authentifier et renvoyer 403 Interdit s’il n’a pas les portées requises par le point de terminaison.

Par exemple, un token avec tickets:read peut récupérer les données de ticket, mais ne peut pas créer ni mettre à jour les tickets. Une tentative d’écriture sans la bonne portée renvoie toujours une erreur 403.

403: You do not have access to this resource

Si cela se produit, l’authentification fonctionne, mais vous devez régénérer le token avec les portées correctes. Pour en savoir plus, voir OAuth Tokens for Grant Types.

Comment utiliser l’authentification JWT pour la messagerie

La messagerie Zendesk dans les applications Web ou mobiles utilise JWT pour identifier les utilisateurs finaux. Votre backend doit signer un token Web JSON avec le secret du Centre d’administration . Zendesk valide le token avant d’associer la session de messagerie à un utilisateur.

Les JWT de messagerie ont besoin de valeurs d’en-tête et de revendication spécifiques pour que Zendesk puisse résoudre l’identité de l’utilisateur.

Au moins, un JWT de messagerie doit inclure :

  • Kid – L’ID clé du Centre d’administration dans l’en-tête JWT, pas la charge utile
  • external_id – Un identifiant unique pour l’utilisateur
  • scope – La valeur « user » pour l’authentification des utilisateurs finaux dans la messagerie

Des revendications facultatives comme le nom, l ' adresse e-mail et email_verified peuvent remplir les détails de l ' utilisateur dans l ' interface d ' agent et Support pour la mise en correspondance des identités par 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 les revendications obligatoires comme external_id ou scope sont absentes ou si vous signez avec le mauvais secret, Zendesk renvoie 401 Non autorisé.

Causes courantes 401 avec JWT :

  • Un secret JWT du mauvais environnement (sandbox vs production)
  • Un token expiré ou des revendications temporelles non valides
  • Les revendications obligatoires comme external_id ou scope ne sont pas présentes
  • Un token signé avec un secret incorrect ou pivoté
  • Un JWT mal formé ou mal codé

Pour déboguer l’authentification de messagerie, commencez par confirmer le secret correct et les réclamations requises. Si l’authentification réussit, mais que le comportement de l’identité semble erroné, vérifiez des valeurs stables et cohérentes pour external_id et tous les champs d’identité facultatifs dans l’ensemble des sessions. Pour en savoir plus, consultez Authentification des utilisateurs.

Les causes courantes d’erreurs 401

Une réponse 401 signifie que Zendesk ne peut pas authentifier la demande et ne peut pas déterminer l’identité de l’appelant.

Des en-têtes d’autorisation incorrects, des tokens désactivés ou des incohérences d’environnement sont à l’origine de la plupart des 401 réponses.

Formatez les en-têtes d’authentification de base comme suit :

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

Les caractères inattendus, les espaces blancs ou les problèmes de codage provoquent souvent des échecs silencieux.

L'API REST Zendesk ne Support pas l'authentification d'origine navigateur. Les demandes JavaScript côté client échouent à cause de CORS, de cookies de session manquants et de workflows d’authentification non pris en charge. Utilisez plutôt un service backend ou une application Zendesk avec le client ZAF .

Les causes courantes des erreurs 403

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

Le manque de portées OAuth provoque la plupart des réponses 403. Par exemple, un token avec tickets:read peut récupérer les tickets, mais ne peut pas les créer ni les mettre à jour. Une tentative d’écriture renvoie toujours une erreur 403.

Vous ne pouvez pas modifier les portées OAuth après la création du token. Si les portées sont erronées, générez un nouveau token.

Autre écueil fréquent : un appel à des points de terminaison réservés aux agents avec des identifiants d’utilisateur final. Les tokens OAuth peuvent appeler /users/me, mais ils renvoient 403 pour les points de terminaison restreints comme les tickets, les vues, ou les champs de ticket.

D'autres causes incluent les tokens révoqués, les règles d'inscription sur la liste autorisée IP et les limites d'accès Multimarque. Dans ce cas, Zendesk rejette la demande car les identifiants sont inactifs ou l’utilisateur ne remplit pas les critères d’accès.

Une approche de dépannage étape par étape

1. Validez les identifiants isolément :

curl -v \
  -u "email/token:token" \
  "https://yoursubdomain.zendesk.com/api/v2/users/me.json"
  • Si cela échoue : Le problème concerne probablement les identifiants ou le compte.
  • Si cela réussit : Les identifiants sont valides. Le problème réside dans la logique ou l’environnement de votre application. Passer à l’étape 2.

2. Vérifiez les limites CORS :

Si curl fonctionne, mais que votre application côté client échoue, vous risquez d’atteindre les restrictions CORS. Ouvrez la console de développement du navigateur et vérifiez l’erreur. Si vous voyez un 401/403 avec un message Access-Control-Allow-Origin, le navigateur bloque la demande avant que Zendesk ne puisse la traiter.

3. Inspecter les en-têtes bruts des demandes :

  • Consignez l’en-tête d’autorisation : Imprimez la chaîne exacte envoyée par votre application. Confirmez qu’il n’y a pas d’espaces blancs masqués et corrigez les préfixes comme Basic ou Bearer.
  • Vérifier l’environnement : Vérifiez que votre application cible le bon sous-domaine. De nombreuses équipes ciblent une URL sandbox avec des identifiants de production, ou l'inverse.

4. Vérifier les portées et les revendications :

  • Pour OAuth : Appelez /api/v2/OAuth/tokens/current pour répertorier les portées actuelles. Vérifiez que le token a la portée requise pour la ressource.
  • Pour la messagerie/JWT : Revalidez votre charge JWT. Confirmez que l’enfant (Key ID) correspond à votre configuration Zendesk et que vous avez utilisé le bon secret de signature.

Réflexions finales

La plupart des erreurs 401 et 403 sur la plateforme des développeurs Zendesk proviennent d’un petit jeu de mauvaises configurations prévisibles. Séparez l’authentification de l’autorisation et vous accélérerez le diagnostic et augmenterez la fiabilité.

Validez vos identifiants tôt, confirmez les champs d’application et les rôles, et suivez une approche de diagnostic structurée pour résoudre les problèmes rapidement et éviter les répétitions en production.

Pour en savoir plus, consultez la documentation Zendesk sur l'accès par token API, l'authentification OAuth, le Zendesk App Framework et l'authentification JWT de 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