This article describes the steps required to create an OAuth flow for your integration and store the resulting third-party token using the ZIS Connections Service.

Use an API testing application such as Postman or command-line tool such as cURL for making API requests described in the following sections.

Create an OAuth client for the target service

Create an OAuth client for your target third-party service. Make sure you set the callback URL as https://zis.zendesk.com/api/services/zis/connections/oauth/callback. The process for this varies depending on the service. You should be provided with a client ID and secret once complete.

Create an OAuth client in ZIS Connections

Make an API request to the Create OAuth Client endpoint to register the details of the third party OAuth service.

Example request

curl \ --request POST \ --url https://<SUBDOMAIN>.zendesk.com/api/services/zis/connections/oauth/clients/<YOUR_INTEGRATION> \ --header 'Authorization: Bearer <ZENDESK_ACCESS_TOKEN>' \ --header 'content-type: application/json' \ --data '{"client_id": "abc","client_secret": "xyz","auth_url": "auth_url","token_url": "token_url"}'

Replace the following placeholders with your own values:

  • <SUBDOMAIN> with your Zendesk subdomain
  • <YOUR_INTEGRATION> with the name of your integration
  • <ZENDESK_ACCESS_TOKEN> with your OAuth token

You will receive the UUID for the OAuth client in the response.

Example response

{ "uuid": "01cc6165-68cd-4031-89a2-dee345874f7c" }

Create an OAuth flow

Make an API request to the Start OAuth Flow endpoint to create an OAuth flow for the OAuth client created in the previous step.

Example request

curl \ --request POST \ --url https://<SUBDOMAIN>.zendesk.com/api/services/zis/connections/oauth/start/<YOUR_INTEGRATION> \ --header 'Authorization: Bearer <ZENDESK_ACCESS_TOKEN>' \ --header 'content-type: application/json' \ --data '{"oauth_client_uuid": "01cc6165-68cd-4031-89a2-dee345874f7c","permission_scopes": "<SCOPES>","origin_oauth_redirect_url": "<YOUR_REDIRECT_ENDPOINT>"}'

This endpoint returns a redirect URL that your service can use to trigger the OAuth flow for the user.

Example response

{  "redirect_url": "https://<SUBDOMAIN>.zendesk.com/api/services/zis/connections/oauth/start_redirect?flow_token=xyz"}

Installation OAuth flow

The following sections describe the installation flow and behavior you would incorporate in your integration. See the ZIS on Zendesk app tutorial series to learn about building an app with OAuth capabilities.

Start the OAuth Redirect

The URL obtained in the previous section redirects the user to the third-party service for authentication and obtains an OAuth token. It then redirects the user back to the origin_oauth_redirect_url when creating the OAuth flow with the verification token added as a query parameter. Example: <YOUR_REDIRECT_ENDPOINT>?verification_token=<VERIFICATION_TOKEN>

Exchange the verification code for an access code and Connection UUID

Your service's origin_oauth_redirect_url (specified when starting the OAuth flow) uses the verification code and makes an API request to the Exchange Verification Code endpoint to exchange it for an access code. This endpoint returns all relevant attributes for a connection.

Example request

curl \ --request GET \ --url https://<SUBDOMAIN>.zendesk.com/api/services/zis/connections/oauth/access_codes/<YOUR_INTEGRATION>?verification_code=<VERIFICATION_TOKEN> \ --header 'Authorization: Bearer <ZENDESK_ACCESS_TOKEN>' \ --header 'content-type: application/json'

Example response

{  "UUID": "355d3d31-e896-1231-b9a2-9f2395b5c943",  "ZendeskAccountID": "YOUR_ACCOUNT_ID",  "Integration": "YOUR_INTEGRATION",  "PermissionScope": "scopes",  "AccessToken": "xyz",  "TokenType": "Bearer",  "RefreshToken": "abc",  "TokenExpiry": "0001-01-01T00:00:00Z",  "OAuthAccessTokenResponseBody": "string",  "OriginOAuthRedirectURL": "http://example.com",  "RawCallbackParams": "string"}

The connection UUID can be used to fetch the access token from the ZIS Connections Service.

Get the connection details by UUID

Make an API request to the Show Connection endpoint to retrieve the access token.

Example request

curl \ --request GET \ --url https://YOUR_SUBDOMAIN.zendesk.com/api/services/zis/connections/<YOUR_INTEGRATION>?uuid=<UUID> \ --header 'Authorization: Bearer <ZENDESK_ACCESS_TOKEN>' \ --header 'content-type: application/json'

Example response

{  "AccessToken": "string",  "CreatedBy": "string",  "Integration": "string",  "OAuthAccessTokenResponseBody": "string",  "PermissionScope": "string",  "RefreshToken": "string",  "TokenExpiry": "2020-07-29T01:23:07Z",  "TokenType": "string",  "UUID": "string",  "ZendeskAccountID": "YOUR_ACCOUNT_ID"}