Si usa la plataforma para desarrolladores de Zendesk, es probable que haya tenido errores 401 o 403. Estos códigos de estado explican muchas solicitudes de API fallidas que vemos de los desarrolladores, especialmente al principio del ciclo de vida de una integración.

Aunque ambos errores se relacionan con el control de acceso, fallan por distintas razones y requieren enfoques diferentes. Si los trata como intercambiables, con frecuencia puede perder tiempo y producir solicitudes fallidas repetidas.

Lo que aprenderá

Al final de esta publicación, entenderá:

  • La diferencia entre 401 errores no autorizados y 403 errores prohibidos en Zendesk
  • Cómo diagnosticar los errores rápidamente
  • Cómo autenticarse correctamente con tokens de API, tokens de acceso OAuth y JWT (Tokens Web JSON)
  • Cómo los ámbitos OAuth afectan la autorización
  • Cómo diagnosticar encabezados mal formados, subdominios incorrectos y credenciales vencidas
  • Cómo corregir los errores con confianza a través de ejemplos prácticos y pasos de resolución de problemas

Diferencia entre los errores 401 y 403

Ambos códigos de estado se relacionan con el control de acceso, pero fallan en distintas etapas del proceso de solicitud.

401 No autorizado

Una respuesta 401 significa que la API de Zendesk no puede autenticar la solicitud. Zendesk no puede identificar a la persona que llama, por lo que no evalúa los permisos ni la lógica de negocio.

Las causas comunes incluyen:

  • Encabezados de autorización ausentes o mal formados
  • Codificación Base64 incorrecta para autenticación básica
  • Formato de correo electrónico y token incorrecto
  • Tokens de API vencidos o revocados
  • Tokens OAuth en un encabezado Autenticación básica
  • JWT no válidos o vencidos para mensajería

Si recibe un error 401, concéntrese en cómo se autentica la solicitud, no en lo que intenta hacer.

403 Prohibido

Una respuesta 403 significa que Zendesk autenticó la solicitud, pero la identidad autenticada carece de permiso para realizar la acción solicitada.

Las causas típicas incluyen:

  • Tokens OAuth sin ámbitos obligatorios
  • Credenciales de usuario final en terminales exclusivos para agentes
  • Acceso a recursos que pertenecen a otra marca
  • Reglas de la lista autorizada de IP de la cuenta
  • Cuentas de agente suspendidas o rebajadas de categoría

Si recibe un error 403, la autenticación se realiza correctamente. El problema es la autorización.

Un flujo de diagnóstico rápido

Cuando se depuran los problemas de acceso, la manera más rápida de avanzar es aislar el problema paso a paso.

  1. Comience con una prueba de rizo. Si la solicitud de curl falla, lo más probable es que el problema involucre credenciales o configuración de la cuenta, no el código de la aplicación
  2. Confirme que llama al subdominio de Zendesk correcto. El ámbito de las credenciales es un entorno específico, y los tokens sandbox y de producción no se intercambian.
  3. Verifique que esté usando el método de autenticación correcto. Las confusiones entre Basic Auth, OAuth y JWT a menudo causan fallas.
  4. Verifique el rol del usuario autenticado. Muchos extremos requieren permisos de agente o administrador, aunque la autenticación tenga éxito
  5. Si usa OAuth, confirme que el token incluya los ámbitos que el extremo requiere
  6. Por último, considere dónde se ejecuta la solicitud. Las solicitudes de origen del navegador a menudo fallan debido a las políticas de Compartir recursos de origen cruzado (CORS) cuando se usa el token de API Autenticación básica u otros flujos del lado del cliente no admitidos. Si tiene que llamar a la API desde un navegador, use un flujo OAuth que admita CORS, envíe solicitudes a través de un servicio backend o use una aplicación de Zendesk con el cliente ZAF. Si desea más información sobre las solicitudes CORS, consulte Realizar solicitudes CORS del lado del cliente a la API de gestión de tickets.

Cómo autenticarse correctamente

La autenticación se ejecuta antes de que se verifique cualquier permiso o lógica de negocio. Si falla la autenticación, Zendesk no puede asociar la solicitud con un usuario o una integración y devuelve un error 401.

Zendesk admite varios métodos de autenticación, cada uno con reglas de formato estrictas.

Autenticación de token de API

Los tokens de API usan la autenticación básica, y el nombre de usuario debe incluir el sufijo / token.

El formato correcto es:

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

Un error común que devuelve un error 401 es la omisión del sufijo / token:

emailAddress:APITOKEN

Un ejemplo de 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());

Autenticación OAuth

Las integraciones que necesitan credenciales duraderas o un control de permisos detallado a menudo usan OAuth. Envíe tokens de acceso OAuth con el esquema Bearer. Use este encabezado:

Authorization: Bearer ACCESS_TOKEN

Solicitud de ejemplo con curl:

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

Un ejemplo de 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());

Una causa común de 401 No autorizado con OAuth es un token de acceso válido enviado con el esquema equivocado. En ese caso, Zendesk no puede autenticar la solicitud y devuelve un 401 antes de evaluar los ámbitos o permisos.

Los tokens OAuth también usan ámbitos que definen las acciones permitidas. Un token puede autenticarse y devolver 403 Prohibido si carece de los ámbitos que requiere el extremo.

Por ejemplo, un token con tickets:read puede obtener datos del ticket, pero no puede crear ni actualizar tickets. Un intento de escritura sin el ámbito correcto siempre devuelve un error 403.

403: You do not have access to this resource

Si esto ocurre, la autenticación funciona, pero debe volver a generar el token con los ámbitos correctos. Si desea ver los detalles del alcance, consulte OAuth Tokens for Grant Types.

Cómo usar la autenticación JWT para la mensajería

La mensajería de Zendesk en aplicaciones web o móviles utiliza JWT para identificar a los usuarios finales. El backend debe firmar un Token Web JSON con el secreto del Centro de administración. Zendesk valida el token antes de asociar la sesión de mensajería con un usuario.

Los JWT de mensajería necesitan valores de encabezado y reclamo específicos para que Zendesk pueda resolver la identidad del usuario.

Como mínimo, un JWT de mensajería debe incluir:

  • kid: la ID clave del Centro de administración en el encabezado de JWT, no la carga
  • external_id: un identificador único para el usuario
  • Ámbito: el valor "usuario" para la autenticación de usuarios finales en la mensajería

Los reclamos opcionales como name, email y email_verified pueden rellenar los detalles del usuario en la interfaz de agente y la coincidencia de identidad basada en correo electrónico de Support.

Ejemplo de generador de 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 no hay reclamos requeridos, como external_id o scope, o si inicia sesión con un secreto equivocado, Zendesk devuelve 401 Unauthorized.

Causas comunes 401 con JWT:

  • Un secreto de JWT del entorno equivocado (sandbox vs producción)
  • Un token vencido o solicitudes temporales no válidas
  • Los reclamos requeridos como external_id o scope no están presentes
  • Un token firmado con un secreto incorrecto o rotado
  • Un JWT mal formado o codificado incorrectamente

Para depurar la autenticación de mensajería, primero confirme el secreto correcto y las afirmaciones requeridas. Si la autenticación tiene éxito pero el comportamiento de identidad parece estar desactivado, verifique valores estables y coherentes para external_id y los campos de identidad opcionales en todas las sesiones. Si desea más información, consulte Authenticating users in your application.

Causas comunes de errores 401

Una respuesta 401 significa que Zendesk no puede autenticar la solicitud ni determinar la identidad de la persona que llama.

Los encabezados de autorización incorrectos, los tokens desactivados o las discrepancias de entorno causan la mayoría de las 401 respuestas.

Formato Encabezados de autenticación básica como estos:

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

Los caracteres inesperados, los espacios en blanco o los problemas de codificación suelen causar fallas silenciosas.

La API de REST de Zendesk Support no admite la autenticación de origen del navegador. Las solicitudes de JavaScript del lado del cliente fallan debido a CORS, faltan cookies de sesión y flujos de autenticación no compatibles. En su lugar, use un servicio backend o una aplicación de Zendesk con el cliente ZAF.

Causas comunes de errores 403

Una respuesta 403 indica que Zendesk autenticó la solicitud, pero las reglas de permisos deniegan el acceso.

La falta de ámbitos OAuth causa la mayoría de las 403 respuestas. Por ejemplo, un token con tickets:read puede obtener tickets pero no puede crearlos ni actualizarlos. Un intento de escritura siempre devuelve un error 403.

Los ámbitos OAuth no se pueden modificar después de la creación del token. Si los ámbitos son incorrectos, genere un nuevo token.

Otro obstáculo frecuente: una llamada a terminales exclusivos para agentes con credenciales de usuario final. Los tokens OAuth de usuario final pueden llamar o llamarme, pero devuelven 403 para terminales restringidos como tickets, vistas o campos de ticket.

Otras causas incluyen tokens revocados, reglas de listas autorizadas de IP y límites de acceso Multimarca. En estos casos, Zendesk rechaza la solicitud porque las credenciales están inactivas o el usuario no cumple los criterios de acceso.

Un enfoque de resolución de problemas paso a paso

1. Validar credenciales de manera aislada:

curl -v \
  -u "email/token:token" \
  "https://yoursubdomain.zendesk.com/api/v2/users/me.json"
  • Si esto falla: El problema probablemente involucra credenciales o la cuenta.
  • Si esto tiene éxito: Las credenciales son válidas. El problema radica en la lógica o el entorno de la aplicación. Mover al paso 2.

2. Verifique los límites de CORS:

Si curl funciona pero la aplicación del lado del cliente falla, lo más probable es que haya restricciones de CORS. Abra la consola para desarrolladores del navegador y revise el error. Si ve un 401/403 con un mensaje Acceso-Control-Permitir-Origen, el navegador bloquea la solicitud antes de que Zendesk pueda procesarla.

3. Inspeccionar encabezados de solicitud sin procesar:

  • Registre el encabezado Autorización: Imprima la cadena exacta que envía su aplicación. Confirme que no haya espacios en blanco ocultos y corrija prefijos como Basic o Bearer.
  • Verificar entorno: Confirme que su aplicación esté dirigida al subdominio correcto. Muchos equipos seleccionan un URL sandbox con credenciales de producción, o al revés.

4. Verificar ámbitos y reclamaciones:

  • Para OAuth: Llamar / API/ v2 / OAuth / tokens/current para mostrar los ámbitos actuales. Confirme que el token tenga el alcance que requiere el recurso.
  • Para mensajería/JWT: Revalide la carga de JWT. Confirme que el ID secundario (ID clave) coincida con la configuración de su cuenta de Zendesk y que haya usado el secreto de firma correcto.

Reflexiones finales

La mayoría de los errores 401 y 403 en la plataforma para desarrolladores de Zendesk provienen de un pequeño conjunto de errores de configuración predecibles. Separe la autenticación de la autorización y acelerará el diagnóstico y aumentará la confiabilidad.

Valide sus credenciales temprano, confirme los ámbitos y roles, y siga un enfoque de diagnóstico estructurado para resolver los problemas rápidamente y evitar repeticiones en producción.

Si desea más detalles, consulte los documentos de Zendesk sobre acceso con token API, autenticación OAuth, Zendesk App Framework y autenticación JWT de mensajería.

Descargo de responsabilidad de la traducción: Este artículo ha sido traducido usando software de traducción automática para proporcionar una idea básica del contenido. Se han realizado esfuerzos razonables para proporcionar una traducción exacta, sin embargo, Zendesk no garantiza la exactitud de la traducción.

Si surge alguna pregunta relacionada con la exactitud de la información incluida en el artículo traducido, consulte la versión en inglés del artículo, que es la versión oficial.

Tecnología de Zendesk