For private integrations, you upload the integrations ZIP file to your Zendesk account. To learn more building an integration app with OAuth flow, see the Zendesk app as an admin interface tutorial series.

The installation and OAuth process should occur when the admin sets up the integration for the first time.

During the installation process of an integration, you’ll need to allow the user to give you permission to access one or more systems. This includes authenticating with Zendesk and other systems.

Installation flow types

Single OAuth flow

If your integration only requires a single authentication with Zendesk, you should aim to keep the user within the Zendesk product without redirecting them anywhere else. This ensures a smooth and consistent experience for your user.

Multiple OAuth flows

A majority of integrations have at least two systems which require connection: Zendesk and at least one third-party system. In this instance, you should design your flow to authenticate with Zendesk first before authenticating with other systems.

A few things to keep in mind:

  • Do not send your users to any more locations than they need
  • Do not ask users to provide authorization for systems which are not part of the integration
  • Request the minimum set of scopes (permissions) that your integration needs
  • Where possible, avoid powerful scopes such as generic "read", "write", or "all" scopes

Multiple connections to one Zendesk instance

Some integrations require multiple external connections to the one Zendesk instance, such as connecting multiple Shopify storefronts to one Zendesk subdomain. In this instance, users must be able to connect and manage multiple connections.

Installation flow process

The installation flow consists of three steps.

Step 1: Connect

Depending on the system, you may need to ask for different values. For example, you would provide a link to the third-party account.

Multiple connections to single Zendesk instance

If your integration allows for multiple connections to one Zendesk subdomain, you should provide extra steps to allow those connections. For example, multiple Slack workspaces connecting to one Zendesk account.

Zendesk recommends allowing the user to name each connection so they can easily identify it.

Step 2: Allow Zendesk permissions

Assuming the Zendesk user is logged in, they should be redirected to give permission for your integration to access Zendesk.

Step 3: Allow third-party permissions

After providing Zendesk permissions, you should then prompt the user to allow your integration to access the third-party application. This redirects the user to the other system to authenticate and allow access. Wherever possible, you should do this in a new browser window rather than navigating away from Zendesk in the primary window.