Designing your installation and OAuth flow for a private integration
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.
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.
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
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.
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.