Si está usando la plataforma para desarrolladores de Zendesk, lo más probable es que haya tenido errores 401 o 403 en algún momento. Estos dos códigos de estado representan un gran porcentaje de las solicitudes de API fallidas que vemos de los desarrolladores, especialmente al principio del ciclo de vida de una integración.

Aunque ambos errores están relacionados con el control de acceso, fallan por razones muy diferentes y requieren enfoques de depuración diferentes. Tratarlos como intercambiables a menudo causa pérdida de tiempo y solicitudes fallidas repetidas.

En esta publicación, explicaremos cómo funcionan los errores 401 y 403 en Zendesk, cómo diagnosticarlos rápidamente y cómo corregirlos con confianza usando ejemplos prácticos y pasos de resolución de problemas.

Lo que aprenderá

Al final de esta publicación, entenderá:

  • La diferencia entre 401 No autorizado y 403 Prohibido en Zendesk
  • Cómo autenticarse correctamente usando tokens de API, tokens de acceso OAuth y JWT
  • Cómo los ámbitos OAuth afectan la autorización
  • Cómo diagnosticar encabezados mal formados, subdominios incorrectos y credenciales vencidas

 

Comprensión 401 vs 403

Si bien ambos códigos de estado se relacionan con el control de acceso, fallan en distintas etapas del procesamiento de la solicitud.

401 No autorizado

Una respuesta 401 significa que la API de Zendesk no pudo autenticar la solicitud. Zendesk no pudo determinar quién es la persona que llama, por lo que no intenta evaluar los permisos ni la lógica comercial.

Las causas comunes incluyen:

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

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

403 Prohibido

Una respuesta 403 significa que la solicitud fue autenticada correctamente, pero la identidad autenticada no tiene permiso para realizar la acción solicitada.

Las causas típicas incluyen:

  • Tokens OAuth faltan ámbitos requeridos
  • Uso de credenciales de usuario final para llamar a terminales solo para agentes
  • Intentar acceder a recursos que pertenecen a otra marca
  • Restricciones de IP activadas en la cuenta
  • Cuentas de agente suspendidas o rebajadas de categoría

Si recibe un error 403, la autenticación está funcionando 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 hacerlo es aislar el problema paso a paso.

Comience por probar su solicitud con Curl. Si la solicitud de curl falla, lo más probable es que el problema sea con las credenciales o la configuración de la cuenta, no con el código de la aplicación.

A continuación, confirme que está llamando al subdominio de Zendesk correcto. Las credenciales están dirigidas a un entorno específico, y los tokens sandbox y de producción no son intercambiables.

Luego verifique que esté usando el método de autenticación correcto. La mezcla de autenticación Basic Auth, OAuth y JWT es una fuente común de fallas.

Verifique el rol del usuario autenticado. Muchos extremos requieren permisos de agente o administrador, incluso si la autenticación se realiza correctamente.

Si está usando OAuth, confirme que el token incluya los ámbitos requeridos por el extremo.

Por último, considere dónde se está ejecutando la solicitud. Las solicitudes de origen del navegador a menudo son bloqueadas por las políticas de Compartir recursos entre navegadores (CORS) cuando se usa la autenticación básica de token de API u otros flujos del lado del cliente no admitidos. Si tiene que llamar a la API desde un navegador, utilice un flujo OAuth que admita CORS, o desvíe las solicitudes a través de un servicio de backend o una aplicación de Zendesk usando 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. 

 

Autenticar correctamente

La autenticación ocurre antes de cualquier verificación de 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 requisitos de formato estrictos.

Autenticación de token de API

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

El formato correcto es:

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

Un error común que resulta en un error 401 es omitir el sufijo / token:

emailAddress:APITOKEN

En Node.js, un ejemplo práctico es como sigue:

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

Los tokens de acceso OAuth se usan comúnmente para integraciones que requieren credenciales de larga duración o un control de permisos detallado. Los tokens OAuth deben enviarse usando el esquema de autenticación del portador. El formato de encabezado correcto es:

Authorization: Bearer ACCESS_TOKEN

Solicitud de ejemplo usando curl:

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

En Node.js, un ejemplo práctico es como sigue:

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 errores 401 No autorizados al usar OAuth es enviar un token de acceso válido con el esquema de autenticación incorrecto. En este caso, Zendesk no puede autenticar la solicitud y devuelve un 401 antes de evaluar los ámbitos o permisos.

Los tokens OAuth también introducen el concepto de ámbitos, que definen explícitamente qué acciones puede realizar el token. Un token puede autenticarse correctamente pero devolver una respuesta 403 Prohibida si carece de los ámbitos requeridos por el extremo al que se llama.

Por ejemplo, un token con tickets:read puede obtener datos del ticket, pero no puede crear ni actualizar tickets. Si se intenta una operación de escritura sin el ámbito apropiado, siempre se producirá un error 403. 

403: You do not have access to this resource

Si esto ocurre, la autenticación está funcionando como se espera, pero el token debe volver a generarse con los ámbitos correctos. Si desea más información sobre los ámbitos, consulte OAuth Tokens for Grant Types.

 

Autenticación JWT para la mensajería

Cuando se implementa la mensajería de Zendesk en aplicaciones web o móviles, la autenticación JWT se usa para identificar a los usuarios finales de manera segura. En este modelo, el backend es responsable de generar y firmar un Token Web JSON (JWT) usando el secreto configurado en Centro de administración. Zendesk valida el token antes de permitir que la sesión de mensajería se asocie con un usuario.

A diferencia de los tokens de API u OAuth, los JWT de mensajería requieren reclamos específicos e información de encabezado que permitan a Zendesk resolver la identidad del usuario correctamente.

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

  • chico: la ID clave del Centro de administración de Zendesk. Esto debe incluirse en el encabezado de JWT, no en la carga útil.
  • external_id: un identificador único para el usuario. Zendesk utiliza este valor como la clave principal al cotejar o crear registros de usuario.
  • Ámbito: debe establecerse en "usuario", lo que indica que el token está destinado a la autenticación de usuarios finales en la mensajería.

Las declaraciones adicionales como name, email y email_verified son opcionales y se pueden incluir para rellenar los detalles del usuario en la interfaz de agente o Support Email-based identity matching.


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 faltan reclamos requeridos como external_id o scope, o si el token está firmado con el secreto equivocado, Zendesk devolverá una respuesta 401 No autorizada.


Las causas comunes de errores de 401 relacionados con JWT incluyen:

  • Usar un secreto de JWT del entorno equivocado (sandbox vs producción)
  • Enviar un token vencido o uno con solicitudes temporales no válidas
  • Omitir declaraciones requeridas como external_id o scope 
  • Firmar el token con un secreto incorrecto o rotado
  • Enviar un JWT mal formado o con codificación incorrecta

Al depurar los problemas de autenticación de mensajería, primero confirme que el token esté firmado con el secreto correcto e incluya las declaraciones requeridas. Si la autenticación tiene éxito pero el comportamiento de identidad del usuario es inesperado, inspeccione los valores utilizados para external_id y los campos de identidad opcionales para asegurarse de que sean estables y coherentes en todas las sesiones. Si desea más información, consulte Autenticación de usuarios en su aplicación.
 

Causas comunes de errores de 401

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

Esto suele deberse a encabezados de autorización, tokens desactivados o desajustes de entorno mal construidos.

Los encabezados Basic Authentication deben tener el siguiente formato o el equivalente:

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

Los caracteres inesperados, los espacios en blanco o los problemas de codificación con frecuencia causan fallas silenciosas.

Por último, recuerde que la API de REST de Zendesk no Support autenticación de origen de navegador. Las solicitudes de JavaScript del lado del cliente fallarán debido a CORS, faltan cookies de sesión y flujos de autenticación no admitidos. En su lugar, use un servicio de backend o una aplicación de Zendesk creada con el cliente ZAF.

 

Causas comunes de errores 403

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

La causa más común es la falta de ámbitos OAuth. Por ejemplo, un token con ticket:read puede obtener tickets pero no puede crearlos ni actualizarlos. Los intentos de escritura siempre devuelven un error 403.

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

Otra fuente común de confusión es intentar llamar a terminales solo para agentes usando credenciales de usuario final. Los tokens OAuth de usuario final pueden funcionar para / usuarios/mí, pero devolverán 403 cuando se llame a extremos restringidos como tickets, vistas o campos de ticket.

Otras causas frecuentes son los tokens revocados, las restricciones de listas autorizadas de IP y las limitaciones de acceso multimarca. En estos casos, la solicitud se rechaza porque las credenciales ya no están activas o porque el usuario no cumple con determinados criterios de acceso.

 

Una estrategia de resolución de problemas paso a paso

1. Validar credenciales de manera aislada En caso de duda, comience por eliminar el código de la aplicación de la ecuación. Valide sus credenciales usando curl:

curl -v \
  -u "email/token:token" \
  "https://your_subdomain.zendesk.com/api/v2/users/me.json"
  • Si esto falla: Es probable que el problema sea una credencial o un problema relacionado con 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. Busque limitaciones de CORS: Si el comando curl funciona pero la aplicación del lado del cliente falla, es probable que esté alcanzando las restricciones de CORS.

Abra la consola para desarrolladores del navegador e inspeccione el error. Si ve un error 401/403 acompañado de un mensaje de consola relacionado con Access-Control-Allow-Origin, el navegador está bloqueando la solicitud antes de que Zendesk pueda procesarla.

3. Inspeccione los encabezados de solicitud sin procesar Si está ejecutando código del lado del servidor (Node.js, Python, PHP, etc.) y aún tiene problemas:

  • Registrar el encabezado de autorización: Imprima la cadena exacta que está enviando su aplicación. Asegúrese de que no haya caracteres ocultos en espacios en blanco o prefijos incorrectos (p. ej., asegúrese de que Basic vs. Bearer se use correctamente).
  • Verificar entorno: Confirme que su aplicación esté dirigida al subdominio correcto. Es común apuntar accidentalmente a un URL sandbox con credenciales de producción, o viceversa.

4. Verificar alcances y afirmaciones Si la autenticación se realiza correctamente pero recibe un 403 Prohibido, es posible que su token carezca de los permisos necesarios.

  • Para OAuth: Verifique los ámbitos actuales llamando al extremo /api/v2/OAuth/tokens/current. Asegúrese de que el token tenga el alcance requerido para el recurso al que está intentando acceder.

  • Para mensajería/JWT: Revalide su carga de JWT. Asegúrese de que la ID de la clave del hijo coincida con la configuración de su cuenta de Zendesk y que el secreto de firma utilizado para generar el token sea correcto.

     

Pensamientos finales

La mayoría de los errores 401 y 403 en la plataforma para desarrolladores de Zendesk se deben a un pequeño número de errores de configuración predecibles. Una vez que se separan claramente las fallas de autenticación de las fallas de autorización, la depuración se vuelve significativamente más rápida y confiable.

Si valida las credenciales pronto, confirma los ámbitos y roles, y sigue un método de diagnóstico estructurado, podrá resolver estos problemas rápidamente y evitar que vuelvan a aparecer en producción.

Si desea más detalles, consulte la documentación de Zendesk sobre el acceso con token API, la autenticación OAuth, el Marco de aplicaciones de Zendesk y la 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