¿Qué plan tengo?
Suite, todas las versiones Team, Growth, Professional, Enterprise o Enterprise Plus
Support Team, Professional o Enterprise

Resumen de IA verificado ◀▼

Use OAuth 2 para autenticar de manera segura las solicitudes de API sin tener que almacenar las contraseñas de los usuarios. Registre su aplicación para generar credenciales de OAuth e implemente el flujo de código de autorización para obtener tokens de acceso. Cuando tenga que actualizar tokens vencidos, utilice el token de actualización.

Ruta de acceso: Centro de administración > Aplicaciones e integraciones > API > Clientes OAuth

Puede utilizar OAuth 2 para autenticar todas las solicitudes API de su aplicación a Zendesk. OAuth brinda una manera segura para que la aplicación pueda tener acceso a los datos de Zendesk sin tener que almacenar ni usar las contraseñas de los usuarios de Zendesk, lo que es información confidencial.

Para usar la autenticación OAuth, es necesario que registre su aplicación en Zendesk. También tendrá que agregar funcionalidad a su aplicación para que admita el flujo de código de autorización de OAuth y actualice los tokens de acceso vencidos.

Zendesk también admite el flujo de tipo de concesión de credenciales de cliente que permite crear un token de acceso usando únicamente un secreto de cliente OAuth. Este tipo de concesión está dirigido solo a clientes confidenciales (tema que no se discute en el presente artículo). Si desea más información, consulte Client credentials grant type en los documentos de referencia de la API.

Temas que se tratan en este artículo:

  • Registrar su aplicación en Zendesk
  • Implementar un flujo de autorización de OAuth en su aplicación
  • Reemplazar los tokens de acceso vencidos

Temas relacionados:

  • Si desea ver un tutorial sobre cómo crear una aplicación web que implementa un flujo de autorización de OAuth, consulte Using OAuth to authenticate Zendesk API requests in a web app.
  • Si desea implementar un flujo de autorización de OAuth en las aplicaciones de Zendesk, consulte Adding third-party OAuth to a Support app.
  • Si no es necesario que los usuarios le den a su aplicación acceso a sus cuentas, de todos modos puede usar los tokens de OAuth para autenticar las solicitudes de la API. Consulte Creating and using OAuth access tokens with the API.

Registrar su aplicación en Zendesk

Es necesario que registre su aplicación para generar credenciales de OAuth que su aplicación pueda usar para autenticar las llamadas API a Zendesk.

Nota: En esta sección se describe cómo configurar un cliente OAuth para los usuarios de una cuenta de Zendesk. Si su aplicación va a interactuar no solo con una sino con varias cuentas de Zendesk, puede solicitar un cliente OAuth global. Un cliente OAuth global es una manera segura y más nítida de autenticar la API con varias instancias de Zendesk. Si desea más información, consulte Set up a global OAuth client (Configurar un cliente OAuth global).

Para registrar su aplicación

  1. En el Centro de administración, haga clic en Aplicaciones e integraciones en la barra lateral y luego seleccione API > Clientes OAuth.
  2. Haga clic en Agregar cliente OAuth al lado derecho de la lista de clientes OAuth.
  3. Complete los siguientes campos para crear un cliente:
    • Nombre: ingrese un nombre para su aplicación. Este es el nombre que verán los usuarios cuando se les solicite que otorguen acceso a la aplicación, y cuando verifiquen la lista de aplicaciones de terceros que tienen acceso a sus cuentas de Zendesk.
    • Descripción: opcional. Una descripción corta de la aplicación que verán los usuarios cuando se les solicite que otorguen acceso a ella.
    • Compañía: opcional. El nombre de la compañía que verán los usuarios cuando se les solicite que otorguen acceso a la aplicación. La información les permitirá saber a quién le están otorgando acceso.
    • Logotipo: opcional. El logotipo que verán los usuarios cuando se les solicite que otorguen acceso a la aplicación. La imagen puede tener formato JPG, GIF o PNG. Para obtener mejores resultados, cargue una imagen cuadrada. Se le cambiará de tamaño para la página de autorización.
    • Identificador: el campo se rellena automáticamente con una versión reformateada del nombre que ingresó para su aplicación. Puede cambiarlo si desea.
    • Tipo de cliente: público o confidencial. Los clientes OAuth públicos son aplicaciones que se ejecutan en entornos donde las credenciales no se pueden almacenar de manera segura, como las aplicaciones móviles y web. Estos clientes tienen que usar PKCE. Los clientes OAuth confidenciales se ejecutan en servidores seguros donde sus credenciales se pueden mantener seguras. Estos clientes pueden usar PKCE, un secreto de cliente, o ambos. Consulte Comprender los tipos de clientes.
    • URL de redireccionamiento: ingrese el URL o los URL que Zendesk debe usar para enviar la decisión del usuario de otorgar acceso a su aplicación. Los URL deben ser absolutos y no relativos, https (salvo que sea localhost o 127.0.0.1), y separados por línea nuevas.
  4. Haga clic en Guardar.

    Después de volver a cargar la página, el campo Secreto que se rellenó automáticamente aparecerá en la parte inferior. Se trata del valor "client_secret" detallado en las especificaciones de OAuth 2.0.

  5. Copie el valor Secreto al portapapeles y guárdelo en un lugar seguro. Nota: Los caracteres pueden sobrepasar el ancho del cuadro de texto, de modo que asegúrese de que ha seleccionado todo antes de copiarlo.
    Importante: Por razones de seguridad, su secreto se mostrará completo solo una vez. Después de hacer clic en Guardar, solo tendrá acceso a los nueve primeros caracteres.
  6. Haga clic en Guardar.

Utilice el identificador único y el valor secreto en su aplicación como se describe en el tema siguiente.

Comprender los tipos de clientes

Los clientes OAuth cuentan con una propiedad kind que puede tener uno de los siguientes valores:

  • Confidencial. Los clientes OAuth confidenciales se ejecutan en servidores seguros donde sus credenciales se pueden mantener seguras. Estos clientes pueden usar PKCE, un secreto de cliente, o ambos.
  • Públicos. Los clientes OAuth públicos son aplicaciones que se ejecutan en entornos donde las credenciales no se pueden almacenar de manera segura, como las aplicaciones móviles y web. Estos clientes tienen que usar PKCE.

Un ejemplo de cliente confidencial son las aplicaciones web del lado del servidor. Una vez que el servidor de autorización proporciona los tokens o las credenciales a la aplicación web, esas credenciales no serán expuestas al exterior.

Algunos ejemplos de clientes públicos son las aplicaciones móviles y las aplicaciones de JavaScript que se ejecutan en clientes que son usuarios-agente como los navegadores web. Las credenciales son fácilmente accesibles (y con frecuencia visibles) en estos clientes.

Los tipos de clientes también se conocen como tipos de cliente en las especificaciones de OAuth. Si desea más información, consulte el apartado sobre Client Types en la documentación de especificaciones de OAuth 2.0.

Esta propiedad se aplica solo al sistema de gestión de tickets de Zendesk Support. No se admite en Chat, Conversaciones o Sell.

Los clientes OAuth existentes de Zendesk tienen actualmente la propiedad kind establecida en unknown. Estos clientes no se verán afectados hasta que la propiedad kind se actualice a public o confidential. Los nuevos clientes OAuth creados en el Centro de administración deben establecer la propiedad kind durante la creación.

Nota: Si está usando un cliente OAuth existente de Zendesk y tiene pensado cambiar la propiedad kind a public, debe implementar PKCE primero. Si no lo hace, el cliente no funcionará, ya que se requerirá PKCE inmediatamente.

Los nuevos clientes OAuth creados en el Centro de administración deben establecer la propiedad kind. Si bien la propiedad kind no es obligatoria para los clientes OAuth que fueron creados con el extremo api/v2/oauth/clients endpoint, Zendesk recomienda incluirla.

Implementar un flujo de autorización de OAuth en su aplicación

Zendesk admite el flujo de concesión de código de autorización para obtener tokens de acceso. A este flujo se le conoce como flujo de concesión de código de autorización porque es necesario obtener un código de autorización antes de solicitar un token de acceso.

El flujo utiliza tokens de actualización, lo que le permite generar nuevos tokens de acceso sin que sea necesario volver a autorizar al usuario. El token de acceso puede caducar si la API proporciona un parámetro expires_in válido, que indica que el token tiene una duración limitada. En estos casos, implemente un mecanismo para obtener un nuevo token de acceso en el momento de su vencimiento usando el token de actualización proporcionado.

Para implementar el flujo de concesión de código de autorización, es necesario agregar la siguiente funcionalidad a su aplicación:

  • Paso 1: Enviar al usuario a la página de autorización de Zendesk
  • Paso 2: Gestionar la decisión de autorización del usuario
  • Paso 3: Obtener un token de acceso de Zendesk
  • Paso 4: Utilizar el token de acceso en llamadas API

Si desea ver un tutorial sobre cómo crear una aplicación web que implementa un flujo de código de autorización de OAuth, consulte Using OAuth to authenticate Zendesk API requests in a web app.

El método de concesión de código de autorización admite PKCE (clave de prueba para el intercambio de código), que agrega una capa de seguridad adicional. Si desea más información, consulte Using PKCE to make Zendesk OAuth access tokens more secure en la documentación para desarrolladores.

Paso 1: Enviar al usuario a la página de autorización de Zendesk

En primer lugar, su aplicación tiene que enviar al usuario a la página de autorización de Zendesk. La página le solicita al usuario que autorice su aplicación para que pueda acceder a Zendesk en nombre del usuario. Una vez que el usuario hace una selección, Zendesk envía la selección y algunos otros fragmentos de información de nuevo a la aplicación.

Para enviar al usuario a la página de autorización de Zendesk

Agregue un vínculo o un botón a su aplicación, que envíe al usuario al siguiente URL: 

https://{subdomain}.zendesk.com/oauth/authorizations/new

donde {subdomain} es su subdominio principal de Zendesk, no un subdominio con mapeo de host.

Se puede usar una solicitud POST o GET. Incluya los siguientes parámetros:

  • response_type: requerido. Zendesk devuelve un código de autorización en la respuesta, de manera que especifique code (código) como el tipo de respuesta. Ejemplo: response_type=code.
  • redirect_uri: requerido. El URL que Zendesk debe usar para enviar la decisión del usuario de otorgar acceso a su aplicación. El URL debe ser absoluto y no relativo. También tiene que ser seguro (https), a menos que se esté usando localhost o 127.0.0.1.
  • client_id: requerido. El identificador único que obtuvo cuando registró su aplicación en Zendesk. Consulte la sección anterior.
  • scope: requerido. Una lista de ámbitos (scopes) separados por espacios que controlan el acceso a los recursos de Zendesk. Se puede solicitar acceso de read, write o impersonate a todos los recursos o bien a recursos específicos. Consulte Especificar el ámbito.
  • state: una cadena arbitraria que se incluye en la respuesta de Zendesk después de que el usuario decide si va a conceder acceso o no. Se puede usar el parámetro para evitar ataques cross-site request forgery (CSRF). En un ataque CSRF, el usuario final es engañado para que haga clic en un vínculo que realiza una acción en una aplicación web donde el usuario final aún está autenticado. Para evitar este tipo de ataques, agregue algún valor al parámetro state (estado) y valídelo cuando vuelva.
  • code_challenge: se requiere si se usa PKCE. Una cadena que representa un desafío de código derivado de un verificador de código. Consulte Generating the code_challenge value en la documentación para desarrolladores.
  • code_challenge_method: se requiere si se usa PKCE. El método utilizado para derivar el desafío de código. Especifique "S256" como el valor.

Asegúrese de usar codificación URL para los parámetros.

Solicitud GET de muestra 

https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&redirect_uri={your_redirect_url}&client_id={your_unique_identifier}&scope=read%20write

La página de autorización de Zendesk se abre en el navegador del usuario final. Una vez que el usuario toma una decisión, Zendesk envía la decisión al URL de redireccionamiento especificado en la solicitud.

Especificar el ámbito

Debe especificar un ámbito para controlar el acceso de la aplicación a los recursos de Zendesk. El ámbito read brinda a una aplicación acceso a las terminales GET. Incluye el permiso para realizar transferencias locales de recursos relacionados. El ámbito write brinda a una aplicación acceso a las terminales POST, PUT y DELETE para crear, actualizar y borrar recursos.

Si desea más información sobre el ámbito, consulte OAuth Tokens for Grant Types.

El ámbito impersonate permite que un administrador de Zendesk haga solicitudes en nombre de los usuarios finales. Consulte Hacer solicitudes de API en nombre de los usuarios finales.

Por ejemplo, el siguiente parámetro proporciona a una aplicación acceso de lectura a todos los recursos: 

"scope": "read"

El siguiente parámetro proporciona acceso de lectura y escritura a todos los recursos: 

"scope": "read write"

Se puede refinar el ámbito de los siguientes recursos:

  • tickets
  • usuarios
  • registros de auditoría (solo lectura)
  • organizaciones
  • centro de ayuda
  • aplicaciones
  • disparadores
  • automatizaciones
  • destinos
  • webhooks
  • zis

La sintaxis es como sigue:

"scope": "resource:scope"

Por ejemplo, el siguiente parámetro limita una aplicación para que solo pueda leer tickets: 

"scope": "tickets:read"

Para darle a una aplicación acceso de lectura y escritura a un recurso, especifique ambos ámbitos: 

"scope": "users:read users:write"

Para darle a una aplicación acceso de escritura a un solo recurso, por ejemplo a organizaciones, y acceso de lectura a todo lo demás: 

"scope": "organizations:write read"

Paso 2: Gestionar la decisión de autorización del usuario

La aplicación debe gestionar la respuesta de parte de Zendesk que le informa lo que ha decidido el usuario. La información se incluye en los parámetros de URL en el URL de redireccionamiento.

Si el usuario decidió otorgar acceso a la aplicación, el URL de redireccionamiento contiene un código de autorización. Ejemplo: 

{redirect_url}?code=7xqwtlf3rrdj8uyeb1yf

El código de autorización solo es válido por 120 segundos.

Si el usuario decidió no otorgar acceso a la aplicación, el URL de redireccionamiento contiene los parámetros error y error_description, que indican a la aplicación que el usuario ha negado el acceso: 

{redirect_url}?error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+request

Utilice estos valores para controlar el flujo de su aplicación. Si el URL contiene un parámetro code, obtenga un token de acceso de Zendesk como se describe en la siguiente sección. Este es el token que se debe incluir en las llamadas API a Zendesk.

Paso 3: Obtener un token de acceso de Zendesk

Si su aplicación recibió un código de autorización de Zendesk como respuesta a que el usuario concedió acceso, su aplicación puede cambiarla por un token de acceso y un token de actualización. Para obtener los tokens, haga una solicitud POST a la terminal Create Token for Grant Type: 

https://{subdomain}.zendesk.com/oauth/tokens
Nota: No confunda esta terminal con la terminal Create Token en la API para tokens OAuth. Ambas terminales devuelven tokens de acceso OAuth válido, pero no comparten la misma ruta, el formato JSON ni los parámetros de solicitud.

Incluya los siguientes parámetros requeridos en la solicitud:

  • grant_type: especifique "authorization_code" como el valor.
  • code: utilice el código de autorización que recibió de Zendesk después de que el usuario concedió acceso.
  • client_id: utilice el identificador único especificado en un cliente OAuth en el Centro de administración de Zendesk (Aplicaciones e integraciones > API > Clientes OAuth). Consulte Registrar su aplicación en Zendesk.
  • client_secret: utilice el secreto especificado en un cliente OAuth en el Centro de administración de Zendesk (Aplicaciones e integraciones > API > Clientes OAuth). Consulte Registrar su aplicación en Zendesk.

    Si se utiliza la PKCE code_challenge y los parámetros code_verifier, no se requiere client_secret. Se puede usar esta característica para migrar del flujo de concesiones implícito, que ya no se recomienda por motivos de seguridad. Consulte Using PKCE to migrate from the implicit grant flow en la documentación para desarrolladores.

  • redirect_uri: el mismo URL de redireccionamiento que en el paso 1. Solo para propósitos de identificación.
  • scope: consulte Especificar el ámbito.
  • code_verifier: se requiere si se usa PKCE. La cadena utilizada para generar el valor code_challenge. Consulte Generating the code_challenge value en la documentación para desarrolladores.
  • expires_in: número de segundos que el token de acceso es válido. Especifique un valor entre 300 segundos (5 minutos) y 172.800 segundos (2 días).
  • refresh_token_expires_in: número de segundos que el token de actualización es válido. Especifique un valor entre 604.800 segundos (7 días) y 7.776.000 segundos (90 días).

Consulte la terminal Create Token for Grant Type en la documentación de referencia de la API si desea más información.

La solicitud debe hacerse a través de https y las propiedades deben tener formato JSON. Si utiliza una aplicación personalizada o de terceros para hacer la solicitud de API, consulte la documentación correspondiente para averiguar el formato correcto para los valores de propiedades.

Usar la biblioteca de solicitudes Python 

response = requests.post(
    f'https://{subdomain}.zendesk.com/oauth/tokens',
    data={
        'grant_type': 'authorization_code',
        'code': f'{your_code}',
        'client_id': f'{your_client_id}',
        'client_secret': f'{your_client_secret}',
        'redirect_uri': f'{your_redirect_url}',
        'scope': 'read',
        'expires in': 172800,
        'refresh_token_expires_in': 800000
    }
)

Respuesta de muestra 

Status: 201 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "refresh_token": "31048ba4d7c601302f3173f243da835f",
  "token_type": "bearer",
  "scope":"read"
}

Guarde el token de acceso y el token de actualización en un almacenamiento de datos seguro para reutilizarlos más adelante.

Paso 4: Utilizar el token de acceso en llamadas API

La aplicación puede usar el token de acceso para realizar llamadas API. Incluya el token en un encabezado de autorización HTTP con la solicitud, como sigue:

Authorization: Bearer {a_valid_access_token}

Por ejemplo, una solicitud en curl para hacer una lista de los tickets sería como sigue: 

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

Reemplazar los tokens de acceso vencidos

Los tokens de acceso caducan después de un tiempo determinado. Utilice el token de actualización que recibió con el token de acceso para solicitar un nuevo token de acceso. Para obtener el nuevo token, no es necesario usar el flujo de código de autorización.

Su aplicación debe implementar un mecanismo alternativo para ocuparse de los tokens de acceso y de actualización vencidos. Por ejemplo, si el token de acceso ha caducado o ha encontrado un error, utilice un controlador (handler) para actualizarlo. Si el proceso de actualización falla o no hay un token de actualización vinculado con el token de acceso, redirija al usuario a https://{subdomain}.zendesk.com/oauth/authorizations/new para volver a autorizar la aplicación.

Detectar si un token de acceso está vencido

Para determinar si un token de acceso ha vencido, haga que su código busque una respuesta 401 después de hacer una solicitud de API con el token. La respuesta incluirá la siguiente cadena JSON: 

{"error":"invalid_token","error_description":"The access token provided is expired, revoked, 
 malformed or invalid for other reasons."}

Si recibe una respuesta 401, haga una llamada al controlador para actualizar el token de acceso usando el token de actualización que recibió junto con el token de acceso.

El siguiente es un ejemplo que usa la biblioteca de solicitudes Python:

url = f'https://{your_subdomain}.zendesk.com/{endpoint}'
headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get(url, headers=headers)
if response.status_code == 401:     # if token has expired or is otherwise invalid
    access_token = refresh_access_token(refresh_token)
    headers['Authorization'] = f'Bearer {access_token}'
    response = requests.get(url, headers=headers)

Actualizar un token de acceso

Para actualizar un token de acceso, haga una solicitud POST a la terminal Create Token for Grant Type: 

https://{subdomain}.zendesk.com/oauth/tokens

Incluya las siguientes propiedades en el cuerpo de la solicitud:

  • grant_type: especifique la cadena "refresh token" como el valor.
  • refresh_token: especifique el valor del token de actualización que recibió con el token de acceso.
  • client_id: use el identificador especificado en el cliente OAuth en el Centro de administración de Zendesk (Aplicaciones e integraciones > API > Clientes OAuth). Consulte Registrar su aplicación en Zendesk.
  • client_secret: use el secreto especificado en el cliente OAuth en el Centro de administración de Zendesk (Aplicaciones e integraciones > API > Clientes OAuth). Consulte Registrar su aplicación en Zendesk.
  • scope: consulte Especificar el ámbito.
  • expires_in: número de segundos que el token de acceso es válido. Especifique un valor entre 300 segundos (5 minutos) y 172.800 segundos (2 días).
  • refresh_token_expires_in: número de segundos que el token de actualización es válido. Especifique un valor entre 604.800 segundos (7 días) y 7.776.000 segundos (90 días).

Consulte la terminal Create Token for Grant Type en la documentación de referencia de la API si desea más información.

El siguiente es un ejemplo de solicitud que usa la biblioteca de solicitudes Python: 

response = requests.post(
    f'https://{your_subdomain}.zendesk.com/oauth/tokens',
    data={
        'grant_type': 'refresh_token',
        'refresh_token': refresh_token,
        'client_id': client_id,
        'client_secret': client_secret,
        'scope': 'read',
        'expires in': 172800,
        'refresh_token_expires_in': 800000
    }
)

La solicitud crea tokens de acceso y de actualización nuevos a la vez que anula los anteriores. Este es un ejemplo de una respuesta: 

Status: 201 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "refresh_token": "31048ba4d7c601302f3173f243da835f,
  "token_type": "bearer",
  "scope": "read"
}

Guarde ambos tokens en un almacenamiento de datos seguro a fin de poder reutilizarlos más adelante.

Tecnología de Zendesk