Si vous utilisez la plateforme destinée aux développeurs, vous avez probablement rencontré des erreurs 401 ou 403. Ces codes de statut prennent en compte de nombreuses demandes API ratées 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 de façon interchangeable, vous risquez souvent de perdre du temps et de répéter le même processus.

Dans cet article, vous apprendrez comment les erreurs 401 et 403 fonctionnent dans Zendesk, comment les diagnostiquer rapidement et comment les résoudre avec assurance grâce à des exemples pratiques et des é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 avec 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

Différence entre 401 et 403

Les deux codes de statut ont trait au 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 de gestion.

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 révoqués ou arrivés à expiration
  • 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 sur la façon dont la demande s’authentifie, pas sur ce qu’elle 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 étendues d’autorisation requises
  • Identifiants de l’utilisateur final par rapport aux points de terminaison réservés aux agents
  • Accès aux ressources qui appartiennent à une autre marque
  • Règles de la liste autorisée pour l’adresse IP du compte
  • Comptes d’agents 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 méthode la plus rapide consiste à identifier le problème étape par étape.

  1. Commencez par un test de la courbure. Si la demande curl échoue, le problème est probablement dû aux identifiants ou à la configuration du compte, pas au code de votre application.
  2. Vérifiez que vous appelez le sous-domaine Zendesk correct. Les identifiants portent sur un environnement spécifique, et les tokens de sandbox et de production ne sont pas interchangeables.
  3. Vérifiez que vous utilisez la méthode d’authentification correcte. Les confusions entre authentification de base, OAuth et JWT sont souvent la cause d’é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, vérifiez que le token inclut les autorisations requises par le point de terminaison.
  6. Enfin, réfléchissez à l’endroit où se trouve la demande. Les demandes provenant du navigateur échouent souvent à cause de politiques CORS (politiques de partage des ressources multi-origines) quand vous utilisez l’authentification de base avec un 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 flux OAuth qui prend en charge CORS, 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 .

Authentifiez-vous correctement

L’authentification s’exécute 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 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 nécessitent des identifiants de longue durée ou un contrôle des permissions détaillé 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 commune 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 étendues d’autorisation qui définissent les actions autorisées. Un token peut effectuer l’authentification et renvoyer 403 Interdit s’il n’inclut pas les autorisations 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 ou mettre à jour des tickets. Si vous essayez d’écrire sans la portée adéquate, vous obtiendrez toujours une erreur 403.

403: You do not have access to this resource

Si cela se produit, l’authentification fonctionne, mais vous devez recréer le token avec les bonnes valeurs. Pour en savoir plus sur la portée, consultez l’article sur les tokens OAuth pour les types d’octroi .

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 Messagerie à un utilisateur.

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

Au minimum, un JWT de messagerie doit inclure :

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

Des revendications facultatives comme name , email et email_verified peuvent remplir les détails d’utilisateur dans l’interface d’agent et 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 absentes, ou si vous signez avec le mauvais secret, Zendesk renvoie 401 Unauthorized.

Causes courantes de 401 avec JWT :

  • Secret JWT du mauvais environnement (sandbox vs production)
  • Token expiré ou revendications temporelles non valides
  • Les revendications obligatoires comme external_id ou scope ne sont pas présentes
  • Token signé avec un secret incorrect ou modifié
  • JWT mal formé ou codé de façon incorrecte

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

Causes courantes des erreurs 401

Avec une réponse 401, 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 erreurs de correspondance d’environnement sont la source de la plupart des réponses 401.

Formatez des 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 sont souvent la cause d’échecs silencieux.

L’API REST Zendesk ne prend pas en assistance l’authentification d’origine du 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 un service backend ou une application Zendesk avec le client ZAF .

Causes courantes des erreurs 403

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

L’absence de valeurs OAuth est la cause de 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 autorisations OAuth après la création du token. Si les champs d’application sont incorrects, générez un nouveau token.

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

Les autres causes incluent les tokens révoqués, les règles de liste autorisée d’adresses IP et les limites d’accès pour plusieurs marques. Dans ce cas, Zendesk refuse la demande car les identifiants ne sont pas actifs ou l’utilisateur ne satisfait pas aux critères d’accès.

Une approche de dépannage détaillée

1. Validez les identifiants séparément :

curl -v \
  -u "email/token:token" \
  "https://yoursubdomain.zendesk.com/api/v2/users/me.json"
  • Si cela ne marche pas : Le problème implique probablement les identifiants ou le 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 CORS :

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

3. Inspectez les en-têtes des demandes brutes :

  • Consigner l’en-tête d’autorisation : Imprimez la chaîne exacte qu’envoie votre application. ne confirmez pas l’absence d’espaces blancs masqués et les préfixes corrects tels que Basic ou Support.
  • Vérifier l’environnement : Vérifiez que votre application cible le bon sous-domaine. De nombreuses équipes ciblent une URL de sandbox avec des identifiants de production ou l’autre.

4. Vérifiez les étendues d’autorisation et les revendications :

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

Dernières réflexions

La plupart des erreurs 401 et 403 sur la plateforme des développeurs Zendesk proviennent d’un petit nombre de mauvaises configurations prévisibles. Vous pouvez séparer l’authentification et l’autorisation pour accélérer le diagnostic et accroître la fiabilité.

Validez rapidement les identifiants, confirmez les portées et les rôles, et suivez une approche de diagnostic structurée pour résoudre rapidement les problèmes et éviter que cela ne se reproduise dans l’environnement de production.

Pour en savoir plus, consultez les documents Zendesk portant sur l’accès par token API , l’authentification OAuth , le framework des applications Zendesk et l’authentification JWT de 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