Alcances de OAuth de la API de Zendesk: Una guía completa para desarrolladores
Stevia Putri
Última edición February 27, 2026
Cuando está creando integraciones con Zendesk, controlar lo que su aplicación puede y no puede hacer es fundamental. Los alcances de OAuth actúan como puertas de permiso, permitiéndole especificar exactamente a qué partes de la API de Zendesk puede acceder su aplicación.
A diferencia de los tokens de API, que otorgan un amplio acceso a toda su cuenta de Zendesk, los alcances de OAuth le permiten seguir el principio del mínimo privilegio. Usted solicita solo los permisos que necesita, nada más. Esto hace que sus integraciones sean más seguras y fáciles de auditar.
En esta guía, repasaremos todo lo que necesita saber sobre los alcances de OAuth de la API de Zendesk: qué son, cuáles están disponibles, cómo implementarlos y las mejores prácticas para mantener sus integraciones seguras.
¿Qué son los alcances de OAuth de la API de Zendesk?
Los alcances de OAuth en Zendesk son declaraciones de permisos que controlan el acceso a los recursos de la API. Cuando crea un token de OAuth, especifica los alcances que determinan qué acciones puede realizar su aplicación: leer tickets, escribir en registros de usuario, administrar contenido del centro de ayuda, etc.
Piense en los alcances como llaves para habitaciones específicas en un edificio. En lugar de tener una llave maestra que abre todas las puertas (como un token de API), usted solicita llaves solo para las habitaciones a las que necesita entrar. Si su integración solo necesita leer datos de tickets, usted solicita el alcance read o tickets:read. No obtendrá acceso para eliminar usuarios o modificar activadores.
Este enfoque granular importa por varias razones:
- Seguridad: Si un token se ve comprometido, el daño se limita a los permisos definidos en el alcance
- Cumplimiento: Puede demostrar exactamente a qué datos accede su aplicación
- Confianza del usuario: Los usuarios finales ven exactamente qué permisos están otorgando durante la autorización de OAuth
- Depuración: Cuando algo se rompe, usted sabe exactamente qué permisos están involucrados
Zendesk admite dos formatos de alcance principales según cómo cree sus tokens. La API de tokens de OAuth utiliza un formato de matriz ("scopes": ["read"]), mientras que el punto final de token de tipo de concesión utiliza una cadena separada por espacios ("scope": "read write"). Cubriremos ambos enfoques en la sección de implementación. Para una comparación más profunda de OAuth frente a los tokens de API, consulte la guía de autenticación de Zendesk.
Alcances de OAuth disponibles en Zendesk
Zendesk organiza los alcances en dos categorías: alcances amplios que se aplican a todos los recursos y alcances específicos de recursos que se dirigen a puntos finales de API individuales.
Alcances amplios
Estos tres alcances controlan el acceso a todos los recursos de Zendesk:
| Alcance | Nivel de acceso | Ideal para |
|---|---|---|
read | Puntos finales GET y carga lateral | Herramientas de informes, paneles de análisis, integraciones de solo lectura |
write | Puntos finales POST, PUT, DELETE | Herramientas de sincronización, plataformas de automatización, integraciones bidireccionales |
impersonate | Solicitudes en nombre de los usuarios finales | Portales de clientes, widgets de soporte integrados, aplicaciones proxy |
El alcance impersonate merece una mención especial. Permite a los administradores realizar solicitudes de API en nombre de los usuarios finales, lo cual es útil al crear aplicaciones orientadas al cliente que necesitan crear tickets o acceder al historial de solicitudes sin exponer las credenciales de administrador. Este alcance requiere privilegios de administrador y debe usarse con cuidado.
Alcances específicos de recursos
Para un control más granular, Zendesk le permite definir permisos de alcance para recursos específicos utilizando la sintaxis resource:scope. Aquí están los recursos que admiten el acceso definido por alcance:
| Recurso | Alcance de lectura | Alcance de escritura | Notas |
|---|---|---|---|
| tickets | tickets:read | tickets:write | Funcionalidad central de tickets |
| users | users:read | users:write | Gestión de usuarios y perfiles |
| organizations | organizations:read | organizations:write | Registros de organización |
| auditlogs | auditlogs:read | N/A | De solo lectura por diseño |
| hc (centro de ayuda) | hc:read | hc:write | Artículos, categorías, secciones |
| apps | apps:read | apps:write | Gestión del mercado de aplicaciones |
| triggers | triggers:read | triggers:write | Automatización de reglas de negocio |
| automations | automations:read | automations:write | Automatizaciones basadas en el tiempo |
| targets | targets:read | targets:write | Destinos de notificación |
| webhooks | webhooks:read | webhooks:write | Configuración de webhook |
| macros | macros:read | macros:write | Respuestas predefinidas |
| requests | requests:read | requests:write | Interfaz de tickets de usuario final |
| satisfaction_ratings | satisfaction_ratings:read | satisfaction_ratings:write | Datos de CSAT |
| dynamic_content | dynamic_content:read | dynamic_content:write | Elementos de contenido dinámico |
| any_channel | N/A | any_channel:write | Solo escritura |
| web_widget | N/A | web_widget:write | Solo escritura |
| zis | zis:read | zis:write | Servicios de integración de Zendesk |
La flexibilidad aquí es poderosa. Puede mezclar y combinar alcances para crear conjuntos de permisos precisos. Por ejemplo, "scopes": ["tickets:read", "users:write", "organizations:read"] le da acceso de lectura a tickets y organizaciones, además de la capacidad de actualizar registros de usuario.
Sintaxis y formato del alcance de OAuth
Obtener la sintaxis correcta es importante porque Zendesk devuelve tokens incluso con formatos de alcance no válidos, pero las llamadas a la API con esos tokens fallarán con errores "Forbidden".
Tokens que no son de tipo de concesión (matriz de alcances)
Cuando utilice la API de tokens de OAuth para crear tokens directamente (generalmente para uso interno o tokens creados por el administrador), utilice el formato de matriz:
{
"token": {
"client_id": 1234,
"scopes": ["tickets:read", "users:read"]
}
}
Puntos clave:
- El nombre del parámetro es
scopes(plural) - El valor es una matriz JSON de cadenas
- Cada alcance es un elemento de matriz separado
- Punto final:
POST /api/v2/oauth/tokens
Tokens de tipo de concesión (cadena de alcance)
Cuando implemente el flujo de autorización de OAuth (código de autorización, token de actualización o credenciales de cliente), utilice el formato de cadena separada por espacios:
{
"grant_type": "authorization_code",
"code": "7xqwtlf3rrdj8uyeb1yf",
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"scope": "tickets:read users:write"
}
Puntos clave:
- El nombre del parámetro es
scope(singular) - El valor es una cadena separada por espacios
- Múltiples alcances van en la misma cadena
- Punto final:
POST /oauth/tokens
Combinaciones de alcance comunes
Aquí hay combinaciones de alcance prácticas para casos de uso típicos:
Informes de solo lectura:
"scopes": ["read"]
Gestión de tickets con búsqueda de usuarios:
"scopes": ["tickets:read", "tickets:write", "users:read"]
Gestión de contenido del centro de ayuda:
"scopes": ["hc:read", "hc:write", "tickets:read"]
Acceso completo de administrador (use con moderación):
"scopes": ["read", "write"]
Cómo implementar los alcances de OAuth en su aplicación
Repasemos la implementación completa, desde la creación de un cliente de OAuth hasta la realización de su primera solicitud de API con alcance.
Paso 1: Cree un cliente de OAuth en Zendesk
Antes de que pueda solicitar tokens con alcance, necesita registrar su aplicación como un cliente de OAuth en Zendesk.
-
Inicie sesión en su cuenta de Zendesk como administrador
-
Navegue a Centro de administración > Aplicaciones e integraciones > API > Clientes de OAuth
-
Haga clic en Agregar cliente de OAuth
-
Complete los campos requeridos:
- Nombre: El nombre de su aplicación (los usuarios verán esto durante la autorización)
- Descripción: Breve descripción de lo que hace su aplicación
- Tipo de cliente: Elija Público para aplicaciones móviles/SPA, Confidencial para aplicaciones del lado del servidor
- URL de redireccionamiento: Sus URL de devolución de llamada (deben ser HTTPS excepto para localhost)
-
Haga clic en Guardar
-
Copie el valor del Secreto inmediatamente (solo se muestra una vez por completo)
-
Anote su Identificador único (este es su
client_id)
Importante: Si selecciona Público como el tipo de cliente, debe implementar PKCE (Clave de prueba para el intercambio de código) por seguridad. Los clientes confidenciales pueden usar PKCE, secreto de cliente o ambos.
Paso 2: Solicite autorización con alcances
Envíe a sus usuarios al punto final de autorización de Zendesk con sus alcances solicitados:
https://{subdominio}.zendesk.com/oauth/authorizations/new?
response_type=code&
redirect_uri=https://su-aplicación.com/callback&
client_id=su_identificador_único&
scope=read%20write&
state=cadena_de_estado_aleatoria
Parámetros requeridos:
response_type=code: Indica que desea un código de autorizaciónredirect_uri: Debe coincidir con una de las URL registradas en el Paso 1client_id: El identificador único de su cliente de OAuthscope: Lista separada por espacios de los alcances solicitados
Parámetros recomendados:
state: Cadena aleatoria para evitar ataques CSRF (valide que esto coincida cuando el usuario regrese)code_challengeycode_challenge_method=S256: Requerido para PKCE con clientes públicos
El usuario verá una pantalla de autorización que enumera los alcances que está solicitando. Aprobarán o denegarán el acceso.
Paso 3: Intercambie el código de autorización por un token de acceso
Cuando el usuario aprueba, Zendesk redirige a su URL de devolución de llamada con un código de autorización:
https://su-aplicación.com/callback?code=7xqwtlf3rrdj8uyeb1yf&state=cadena_de_estado_aleatoria
Intercambie este código por un token de acceso:
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://su-aplicación.com/callback",
"scope": "read write"
}'
Importante: El código de autorización caduca en 120 segundos. Intercámbielo rápidamente.
La respuesta incluye su token de acceso y token de actualización:
{
"access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
"refresh_token": "31048ba4d7c601302f3173f243da835f",
"token_type": "bearer",
"scope": "read write",
"expires_in": 172800,
"refresh_token_expires_in": 800000
}
Paso 4: Utilice el token de acceso en las solicitudes de API
Incluya el token en sus solicitudes de API como un token Bearer:
curl https://{subdominio}.zendesk.com/api/v2/tickets.json \
-H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"
El token solo funciona para los puntos finales que coinciden con sus alcances. Un token con el alcance tickets:read puede obtener tickets pero no puede crearlos (eso requeriría tickets:write).
Configuraciones de alcance comunes para casos de uso típicos
Diferentes integraciones necesitan diferentes conjuntos de permisos. Aquí hay configuraciones que vemos con frecuencia:
Herramientas de informes y análisis
Estas herramientas solo necesitan leer datos:
"scope": "read"
O más restrictivo:
"scope": "tickets:read users:read organizations:read"
Integraciones de sincronización bidireccional
Las herramientas de sincronización necesitan leer y escribir en múltiples recursos:
"scope": "tickets:read tickets:write users:read users:write organizations:read organizations:write"
Gestión de contenido del centro de ayuda
Para la gestión de artículos de la base de conocimientos:
"scope": "hc:read hc:write"
Portales orientados al cliente
Cuando su aplicación actúa en nombre de los usuarios finales:
"scope": "requests:read requests:write impersonate"
Herramientas de automatización y flujo de trabajo
Para herramientas que gestionan reglas de negocio:
"scope": "triggers:read triggers:write automations:read automations:write webhooks:read webhooks:write"
Solución de problemas de errores relacionados con el alcance
Incluso con una implementación adecuada, encontrará errores. Aquí le mostramos cómo manejar los más comunes:
Errores "Forbidden" (403)
Este es el error más común relacionado con el alcance. Significa que su token carece de permiso para el punto final solicitado.
Causas:
- Falta el alcance requerido para el punto final
- Formato de alcance no válido (desajuste de matriz frente a cadena)
- El rol del usuario no tiene permiso (los alcances de OAuth están restringidos por los permisos del usuario)
Solución: Verifique qué alcance requiere el punto final en la documentación de la API de Zendesk, luego verifique que su token lo incluya. Recuerde que algunos puntos finales requieren privilegios de administrador independientemente de los alcances de OAuth. Para obtener más detalles sobre la creación y gestión de tokens, consulte el tutorial de tokens de OAuth de Zendesk.
401 No autorizado
Esto indica un token caducado o revocado:
{
"error": "invalid_token",
"error_description": "The access token provided is expired, revoked, malformed or invalid for other reasons."
}
Solución: Utilice su token de actualización para obtener un nuevo token de acceso, o redirija al usuario a través del flujo de autorización nuevamente si el token de actualización también ha caducado.
Formato de alcance no válido
Si pasa los alcances en el formato incorrecto (matriz cuando se espera una cadena, o viceversa), Zendesk aún puede emitir un token, pero las llamadas a la API fallarán.
Solución: Verifique dos veces qué punto final está utilizando:
/api/v2/oauth/tokensutiliza el formato de matriz"scopes": []/oauth/tokensutiliza el formato de cadena"scope": ""
Desajuste de alcance frente a rol
Los alcances de OAuth se filtran por el rol del usuario. El token de OAuth de un agente no puede acceder a los puntos finales solo para administradores, incluso si el token tiene el alcance write.
Solución: Asegúrese de que el usuario que autoriza su aplicación tenga los permisos de rol necesarios para los requisitos de su integración.
Mejores prácticas para la seguridad del alcance de OAuth
Seguir estas prácticas mantendrá seguras sus integraciones de Zendesk:
Solicite alcances mínimos
Solo solicite los permisos que absolutamente necesita. Si su integración solo lee tickets, no solicite el alcance write. Esto limita la exposición si un token se ve comprometido.
Utilice clientes confidenciales cuando sea posible
Las aplicaciones del lado del servidor deben usar clientes confidenciales con secretos de cliente. Los clientes públicos (aplicaciones móviles, SPA) deben implementar PKCE.
Implemente la lógica de actualización de tokens
Los tokens de acceso caducan. Querrá incorporar la lógica de actualización automática en su aplicación:
response = requests.get(api_url, headers=headers)
if response.status_code == 401:
new_token = refresh_access_token(refresh_token)
headers['Authorization'] = f'Bearer {new_token}'
response = requests.get(api_url, headers=headers)
Almacene los tokens de forma segura
Trate los tokens de acceso y los tokens de actualización como contraseñas. Almacénelos encriptados, nunca los registre y no los exponga en el código del lado del cliente.
Valide los parámetros de estado
Siempre incluya y valide el parámetro state en su flujo de OAuth para evitar ataques CSRF.
Considere usar una plataforma de integración segura
La creación de integraciones de OAuth de forma segura requiere una atención cuidadosa al almacenamiento de tokens, la lógica de actualización y el manejo de errores. Si está creando integraciones de atención al cliente, considere usar una plataforma como eesel AI que maneje Zendesk OAuth de forma segura con la gestión de alcance adecuada incorporada. Nuestro Agente de IA se integra con Zendesk utilizando los alcances mínimos requeridos, siguiendo el principio del mínimo privilegio de forma predeterminada. También puede obtener más información sobre cómo ver y gestionar sus tokens de OAuth en la documentación de Zendesk.
Conclusión
Los alcances de OAuth de la API de Zendesk le brindan un control preciso sobre a qué pueden acceder sus integraciones. Al comprender los alcances disponibles, implementarlos correctamente y seguir las mejores prácticas de seguridad, puede crear integraciones que sean poderosas y seguras.
Las conclusiones clave:
- Utilice alcances amplios (
read,write) para integraciones simples, alcances específicos de recursos para un control granular - Haga coincidir su formato de alcance con su punto final de token (matriz frente a cadena)
- Siempre solicite permisos mínimos
- Maneje la caducidad del token con elegancia con la lógica de actualización
- Recuerde que los roles de usuario restringen los alcances de OAuth
Ya sea que esté creando una herramienta de informes simple o una sincronización bidireccional compleja, la configuración de alcance adecuada es la base de una integración segura de Zendesk.
Preguntas frecuentes
Share this article
Article by
Stevia Putri
Stevia Putri is a marketing generalist at eesel AI, where she helps turn powerful AI tools into stories that resonate. She’s driven by curiosity, clarity, and the human side of technology.
