Autenticación y ámbitos de la API de Zendesk: Una guía completa para 2026

Si está creando una integración con Zendesk, la autenticación es su primer obstáculo. Si lo hace mal, pasará horas depurando misteriosos errores 403. Si lo hace bien, tendrá una conexión segura y mantenible que simplemente funciona.

Esta guía cubre todo lo que necesita saber sobre la autenticación de la API de Zendesk en 2026. Repasaremos los diferentes métodos de autenticación, explicaremos cómo funcionan los ámbitos de OAuth y le mostraremos exactamente cómo implementarlos con ejemplos de código que funcionan.

En eesel AI, creamos integraciones con Zendesk todos los días. Hemos visto lo que funciona, lo que falla y cómo evitar los errores comunes que hacen tropezar a los desarrolladores.

Comprender los métodos de autenticación de la API de Zendesk

Zendesk ofrece tres formas de autenticar las solicitudes de la API, aunque una de ellas se está eliminando gradualmente. Analicemos sus opciones.

Las tres opciones de autenticación

La autenticación con contraseña está obsoleta y Zendesk recomienda migrar a tokens de API u OAuth. Si está empezando de cero, omita las contraseñas por completo.

Autenticación con token de API

Los tokens de API son la opción más sencilla. Son contraseñas autogeneradas que se crean en el Centro de administración de Zendesk (Zendesk Admin Center).

Así es como funcionan las credenciales:

{dirección_de_correo_electrónico}/token:{token_de_api}

Por ejemplo:

jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

Cuando codifica esta cadena en base64, su encabezado de autorización (Authorization header) se ve así:

Authorization: Basic amRvZUBleGFtcGxlLmNvbS90b2tlbjo2d2lJQldiR2tCTW8xbVJETXVWd2t3MUVQc05rZVVqOTVQSXoyYWt2

O con curl:

curl https://yourdomain.zendesk.com/api/v2/users.json \
  -u jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

Limitaciones clave que debe conocer:

• Puede tener hasta 256 tokens activos (2048 si ya superó los 256)
• Los tokens pueden suplantar a cualquier usuario de la cuenta, incluidos los administradores
• Sin permisos granulares: un token tiene el mismo acceso que el usuario que lo creó
• Los tokens no caducan a menos que los revoque manualmente

Fuente: Documentos de seguridad y autenticación de Zendesk (Zendesk Security and Authentication Docs)

Autenticación con token de acceso OAuth

OAuth es la mejor opción para la mayoría de las integraciones. Le brinda un control granular sobre los permisos a través de los ámbitos, y los tokens están vinculados a usuarios específicos en lugar de tener un amplio acceso a la cuenta.

El flujo funciona así:

1. Su aplicación redirige al usuario a Zendesk para autorizar el acceso
2. El usuario otorga permiso y Zendesk envía un código de autorización a su aplicación
3. Su aplicación intercambia el código por un token de acceso
4. Utiliza el token Bearer en las solicitudes de la API

Así es como se ve una solicitud:

curl https://yourdomain.zendesk.com/api/v2/users.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

OAuth también admite solicitudes de API del lado del cliente desde navegadores, lo que los tokens de API no pueden hacer debido a las restricciones de CORS.

Fuente: Documentación de ayuda de Zendesk OAuth (Zendesk OAuth Help Documentation)

Ámbitos de OAuth explicados

Los ámbitos son el corazón de la seguridad de OAuth. Le permiten solicitar solo los permisos que su aplicación realmente necesita, siguiendo el principio del privilegio mínimo.

¿Qué son los ámbitos de OAuth?

Piense en los ámbitos como permisos. En lugar de obtener acceso completo a una cuenta de Zendesk, solicita capacidades específicas. Una herramienta de informes podría necesitar solo acceso de lectura a los tickets. Una herramienta de sincronización necesita acceso de lectura y escritura. Un panel de administración podría necesitar derechos de suplantación para actuar en nombre de los usuarios.

Ámbitos amplios

Estos otorgan acceso general a todos los recursos:

• read: Acceso a los puntos finales GET y a la carga lateral de recursos relacionados (sideloading related resources)
• write: Acceso a los puntos finales POST, PUT y DELETE para crear, actualizar y eliminar
• impersonate: Permite a los administradores realizar solicitudes en nombre de los usuarios finales

Ámbitos específicos de recursos

Para un control más preciso, puede limitar los permisos a recursos específicos:

Algunos recursos son de solo escritura: any_channel:write y web_widget:write.

Fuente: Referencia de la API de tokens OAuth de Zendesk (Zendesk OAuth Tokens API Reference)

Diferencias de formato de ámbito (¡importante!)

Aquí es donde los desarrolladores a menudo se equivocan. Zendesk utiliza diferentes formatos según el punto final que utilice:

Para la API de tokens OAuth (/api/v2/oauth/tokens):

{
  "token": {
    "client_id": 1234,
    "scopes": ["tickets:read", "users:read"]
  }
}

Para el flujo de autorización (/oauth/tokens):

{
  "grant_type": "authorization_code",
  "scope": "tickets:read users:read"
}

El primero usa una matriz. El segundo usa una cadena separada por espacios. Mezcle estos y obtendrá errores confusos.

Implementación de la autenticación OAuth

Repasemos la implementación completa, paso a paso.

Paso 1: Crear un cliente OAuth

Primero, debe registrar su aplicación en Zendesk.

1. En el Centro de administración de Zendesk (Zendesk Admin Center), vaya a Aplicaciones e integraciones > API > Clientes OAuth (OAuth clients)

2. Haga clic en Agregar cliente OAuth (Add OAuth client)

3. Rellene los detalles:

   • Nombre (Name): El nombre de su aplicación (los usuarios lo ven al autorizar)
   • Descripción (Description): Breve explicación de lo que hace su aplicación
   • Tipo de cliente (Client kind): Elija Público (Public) para aplicaciones móviles/SPA o Confidencial (Confidential) para aplicaciones del lado del servidor
   • URL de redireccionamiento (Redirect URLs): Sus URL de devolución de llamada (deben ser HTTPS excepto para localhost)

4. Haga clic en Guardar (Save)

5. Copie el valor del Secreto (Secret) inmediatamente. Solo se muestra una vez.

6. Anote su Identificador único (Unique Identifier) (este es su client_id)

Comprensión de los tipos de clientes:

• Los clientes confidenciales (Confidential clients) se ejecutan en servidores seguros donde las credenciales pueden protegerse. Pueden usar PKCE, secretos de cliente o ambos.
• Los clientes públicos (Public clients) se ejecutan en navegadores o aplicaciones móviles donde las credenciales son visibles. Deben usar PKCE por seguridad.

Si está creando una integración del lado del servidor, elija Confidencial. Para aplicaciones JavaScript o aplicaciones móviles, elija Público.

Fuente: Documentación de ayuda de Zendesk OAuth (Zendesk OAuth Help Documentation)

Paso 2: Solicitar autorización

Envíe a sus usuarios a la página de autorización de Zendesk:

https://{subdominio}.zendesk.com/oauth/authorizations/new?
  response_type=code&
  redirect_uri=https://suaplicacion.com/callback&
  client_id=su_identificador_único&
  scope=read%20write&
  state=cadena_aleatoria_de_estado

Parámetros requeridos:

• response_type=code (quiere que se devuelva un código de autorización)
• redirect_uri (debe coincidir con lo que registró)
• client_id (su identificador único)
• scope (lista de permisos separados por espacios)

Opcional pero recomendado:

• state (cadena aleatoria para evitar ataques CSRF)
• code_challenge y code_challenge_method=S256 (para PKCE)

El usuario ve una página de autorización que le pregunta si desea otorgar acceso a su aplicación. Si aprueba, Zendesk redirige a su redirect_uri con un código de autorización:

https://suaplicacion.com/callback?code=7xqwtlf3rrdj8uyeb1yf

Importante: El código de autorización caduca en 120 segundos. Intercámbielo rápidamente.

Paso 3: Intercambiar código por token de acceso

Realice una solicitud POST para intercambiar el código:

curl https://{subdominio}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "7xqwtlf3rrdj8uyeb1yf",
    "client_id": "su_identificador_único",
    "client_secret": "su_secreto_de_cliente",
    "redirect_uri": "https://suaplicacion.com/callback",
    "scope": "read write",
    "expires_in": 172800,
    "refresh_token_expires_in": 7776000
  }'

Obtendrá una respuesta como:

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "refresh_token": "31048ba4d7c601302f3173f243da835f",
  "token_type": "bearer",
  "scope": "read write",
  "expires_in": 172800,
  "refresh_token_expires_in": 7776000
}

Almacene ambos tokens de forma segura. El token de acceso se utiliza para las llamadas a la API. El token de actualización le permite obtener un nuevo token de acceso cuando caduca el actual.

Configuración de caducidad del token:

• expires_in: 300 segundos (5 minutos) a 172 800 segundos (2 días)
• refresh_token_expires_in: 604 800 segundos (7 días) a 7 776 000 segundos (90 días)

Fuente: Documentación de ayuda de Zendesk OAuth (Zendesk OAuth Help Documentation)

Paso 4: Realizar solicitudes de API autenticadas

Ahora use su token de acceso:

curl https://{subdominio}.zendesk.com/api/v2/tickets.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

O en Python:

import requests

headers = {
    "Authorization": f"Bearer {access_token}"
}
response = requests.get(
    "https://yourdomain.zendesk.com/api/v2/tickets.json",
    headers=headers
)

O en Node.js:

const axios = require('axios');

const response = await axios.get(
  'https://yourdomain.zendesk.com/api/v2/tickets.json',
  {
    headers: {
      'Authorization': `Bearer ${access_token}`
    }
  }
);

Cuando caduque el token de acceso, utilice el token de actualización para obtener uno nuevo sin necesidad de que el usuario vuelva a autorizar.

Configuraciones de ámbito comunes por caso de uso

Las diferentes integraciones necesitan diferentes permisos. Aquí hay configuraciones de ámbito típicas para escenarios comunes.

Herramientas de informes de solo lectura

Para paneles que extraen datos de tickets sin realizar cambios:

read

O más específicamente:

tickets:read users:read organizations:read

Esto le da a su herramienta acceso para ver tickets, usuarios y organizaciones sin la capacidad de modificar nada.

Integraciones de sincronización bidireccional

Para sincronizar Zendesk con un CRM u otros sistemas:

tickets:read tickets:write users:read users:write organizations:read organizations:write

Esto le permite leer los datos existentes y enviar las actualizaciones de vuelta a Zendesk.

Gestión de contenido del Centro de ayuda

Para herramientas que gestionan artículos de la base de conocimientos:

hc:read hc:write

Esto limita los permisos al contenido del Centro de ayuda únicamente, manteniendo los tickets y los datos del usuario fuera del alcance.

Portales orientados al cliente

Para widgets integrados donde los usuarios finales crean y ven sus propios tickets:

requests:read requests:write impersonate

El ámbito impersonate permite a su aplicación crear tickets en nombre de los usuarios finales sin necesidad de que tengan cuentas de Zendesk.

Solución de problemas de errores de autenticación

Incluso con la configuración correcta, las cosas salen mal. Aquí se explica cómo solucionar los problemas más comunes.

Errores 403 Prohibido

Un 403 significa que su token es válido, pero no tiene permiso para esa acción.

Causas:

• Falta el ámbito requerido para el punto final
• Formato de ámbito incorrecto (matriz frente a cadena)
• La función del usuario no permite esa acción (por ejemplo, un agente que intenta utilizar puntos finales solo para administradores)

Solución: Consulte la documentación de la API (API documentation) para conocer el ámbito requerido del punto final. Verifique que su token tenga ese ámbito utilizando el punto final Mostrar token (Show Token endpoint).

Errores 401 No autorizado

Un 401 significa que su token no es válido, ha caducado o está mal formado.

Causas:

• El token ha caducado (si estableció una caducidad)
• El token fue revocado por el usuario o un administrador
• El formato del token es incorrecto (falta el prefijo "Bearer", por ejemplo)

Solución: Actualice el token si tiene un token de actualización. De lo contrario, redirija al usuario a través del flujo de autorización nuevamente.

Errores comunes de OAuth

Fuente: Documentación de ayuda de Zendesk OAuth (Zendesk OAuth Help Documentation)

Prácticas recomendadas de seguridad para la autenticación de la API de Zendesk

Hacer que la autenticación funcione es el primer paso. Mantenerla segura es continuo.

Gestión de tokens

• Almacene los tokens cifrados: Nunca almacene los tokens en texto sin formato ni los confirme en los repositorios de código
• Implemente la rotación automática: Actualice los tokens antes de que caduquen para evitar interrupciones del servicio
• Elimine los tokens no utilizados: Revoque los tokens para las integraciones que ya no utilice
• Supervise el uso de tokens: Zendesk realiza un seguimiento de cuándo se utilizan los tokens. Esté atento a la actividad inesperada

Selección de ámbito

• Solicite ámbitos mínimos: Solo solicite los permisos que su aplicación realmente necesita
• Revise los permisos otorgados: Audite periódicamente los ámbitos que tienen sus tokens
• Documente los requisitos de ámbito: Mantenga un registro de por qué se necesita cada ámbito para el cumplimiento

Seguridad de la integración

• Utilice HTTPS para todas las solicitudes: La API de Zendesk es solo SSL y requiere TLS 1.2
• Implemente PKCE para clientes públicos: Requerido para aplicaciones móviles y basadas en navegador
• Valide los parámetros de estado: Siempre verifique que el parámetro de estado coincida con lo que envió para evitar ataques CSRF
• Admite SNI: Su cliente HTTP debe admitir la extensión TLS de indicación de nombre de servidor (Server Name Indication)

Fuente: Documentos de seguridad y autenticación de Zendesk (Zendesk Security and Authentication Docs)

Creación de integraciones seguras de Zendesk con eesel AI

Si todo esto le parece mucho para administrar, no está solo. La autenticación es una de las partes más propensas a errores de la creación de integraciones de Zendesk.

En eesel AI, gestionamos OAuth de Zendesk de forma segura para que no tenga que preocuparse por la gestión de tokens, la configuración de ámbitos o la lógica de actualización. Nuestra integración de Zendesk viene con ámbitos preconfigurados que siguen el principio del privilegio mínimo, la actualización automática de tokens y el manejo de errores incorporado para problemas de autenticación comunes.

También ofrecemos un Agente de IA (AI Agent) que puede trabajar con sus datos de Zendesk para automatizar los flujos de trabajo de soporte. Se conecta a través del mismo flujo OAuth seguro, con ámbitos limitados exactamente a lo que necesita la automatización.

Ya sea que lo cree usted mismo o utilice una plataforma como la nuestra, la clave es obtener la autenticación correcta desde el principio. Una base segura facilita todo lo demás.

Ya sea que lo cree usted mismo o utilice una plataforma como la nuestra, la clave es obtener la autenticación correcta desde el principio. Una base segura facilita todo lo demás.