A ZIS connection stores an OAuth access token for a service, such as Slack, Shopify, or Zendesk. You can use a connection to authenticate API requests in a ZIS flow.

Managing ZIS connections

You manage connections using the ZIS OAuth Connections API. In a typical setup, an admin uses a private Zendesk app to connect a ZIS integration to a service. To do this, the app uses the ZIS Connections API to start and complete an OAuth flow with the service. The app also handles any redirects and admin interactions required for the OAuth flow.

When the OAuth flow completes, the service sends ZIS an OAuth access token. ZIS stores this token in a connection in the ZIS Connections Service. You can then use the connection's token to authenticate API requests for custom actions in a ZIS flow.

For an example of this setup, see the Zendesk app as an admin interface tutorial series.

Supported grant types

ZIS connections support the authorization code grant type. ZIS connections also support the refresh token grant type through access token refreshes. You can't use a ZIS connection to store access tokens resulting from other grant types.

Creating a ZIS connection

This section contains instructions for creating a connection without a Zendesk app. The instructions use only cURL requests and a web browser. This is useful when building or testing a ZIS integration. The instructions use the same API calls and workflow you'd use in a Zendesk app.

What you'll need

To complete the steps in this section, you'll need:

Note: The steps in Obtaining a ZIS OAuth token don't create a ZIS connection. We only recommend using connections to authenticate API requests in a ZIS flow.

Creating a ZIS connection for a third-party service

To create a connection for a third-party service, you first need to create an OAuth client in the service. You then need to register the OAuth client in ZIS. ZIS uses the client to pass data to the service during an OAuth flow.

Note: The steps for creating a Zendesk connection differ from other services. To create a Zendesk connection, see Creating a ZIS connection for Zendesk.

  1. Create an Oauth client in the third-party service. These steps vary based on the service. Set the client's callback URL as https://zis.zendesk.com/api/services/zis/connections/oauth/callback. When done, the service should provide an id and secret for the OAuth client.

  2. Make a Create OAuth Client request to register the service's OAuth client in ZIS. For example, the following request creates an OAuth client for Slack. The client is named "slack".

    curl -X POST https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/clients/{integration} \  -H "Authorization: Bearer {access_token}" \  -H "Content-type: application/json" \  -d '  {    "name": "slack",    "client_id": "CLIENT_ID",    "client_secret": "CLIENT_SECRET",    "default_scopes": "chat.postMessage",    "auth_url": "https://slack.com/oauth/v2/authorize",    "token_url": "https://slack.com/api/oauth.v2.access"  }'
  3. Make a Start OAuth Flow request to start an OAuth flow with the service. Specify the name of the OAuth client from the previous step in oauth_client_name. For example, the following request creates a connection named "slack". The connection uses the "slack" OAuth client.

    Important: Don't use a name of "zendesk." This name is reserved for Zendesk connections.

    If you're creating a connection without a Zendesk app, leave the origin_oauth_redirect_url value as "https://example.local".

    To pass an access_type query parameter of "offline" in the OAuth flow's authorization request, set allow_offline_access to "true". Some third-party services, such as the Google APIs, require this setting to let ZIS or other applications refresh access tokens without a user present.

    curl -X POST https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/start/{integration} \  -H "Authorization: Bearer {access_token}" \  -H 'content-type: application/json' \  -d '{    "name": "slack",    "oauth_client_name": "slack",    "origin_oauth_redirect_url": "https://example.local",    "permission_scopes": "chat:write",    "allow_offline_access": false  }'

    The request returns a redirect URL.

    {  "redirect_url": "https://zis.zendesk.com/api/services/zis/connections/oauth/start_redirect?flow_token=xyz"}
  4. In a typical setup, the Zendesk app opens the redirect URL for the admin. If you're creating a connection without an app, open the redirect URL in a web browser. The URL redirects you to an OAuth authorization page for the service. Complete the authorization steps on the page.

  5. After authorization, the service redirects you to the origin_oauth_redirect_url from the Start OAuth Flow request. The URL now includes a verification_token query parameter. The parameter contains an OAuth verification code for the service.

    If you used an origin_oauth_redirect_url of "https://example.local", the URL returns a browser error. This is expected and doesn't interfere with the creation of the connection. You can safely close the browser tab.

    Outside the browser, ZIS makes an authorization code request to the service. If the request is successful, the service returns an access token response.

    ZIS stores the response's access token in a connection. If provided, ZIS also stores the response's expiration time and refresh token in the connection. The connection uses the name you specified in the Start OAuth Flow request.

  6. As an optional step, verify the new connection using a Show OAuth Connection request. The following request fetches a connection named "slack".

    curl https://{subdomain}.zendesk.com/api/services/zis/connections/{integration}?name=slack \  -H "Authorization: Bearer {access_token}"

    The response contains information about the connection, including its access_token.

    {  "uuid": "***uuid***",  "name": "slack",  "zendesk_account_id": 12345678,  "integration": "example_zendesk_to_slack",  "permission_scope": "chat:write",  "access_token": "***access token***",  "token_type": "bot",  "refresh_token": "",  "token_expiry": "0001-01-01T00:00:00Z",  "oauth_access_token_response_body": "",  "oauth_url_subdomain": "example",  "created_by": "1234567890123",  "created_at": "2099-05-16T15:33:19Z"}

Refreshing access tokens

ZIS can automatically refresh expired access tokens for connections that include a refresh token. To enable automatic refreshes:

  • Set allow_offline_access to "true" in the connection's Start OAuth Flow request, if needed. Some services require this setting to refresh access tokens without a user present.

  • Ensure the service's access token response includes non-empty expires_in and refresh_token values. ZIS can't refresh access tokens for a service that doesn't provide these values.

Creating a ZIS connection for Zendesk

When you register a ZIS integration, the request automatically creates a Zendesk OAuth client in ZIS. This client is named "zendesk". You can use this client to start an OAuth flow. The OAuth flow uses the authorization code grant type. The resulting Zendesk access token doesn't expire or use refresh tokens.

  1. Make a Start OAuth Flow request to start an OAuth flow with Zendesk. In the request, specify a name and oauth_client_name of "zendesk". Specify our Zendesk subdomain in oauth_url_subdomain.

    If you're creating a connection without a Zendesk app, leave origin_oauth_redirect_url as "https://example.local".

    curl -X POST https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/start/{integration} \  -H "Authorization: Bearer {access_token}" \  -H 'content-type: application/json' \  -d '{    "name": "zendesk",    "oauth_client_name": "zendesk",    "oauth_url_subdomain": "ZENDESK_SUBDOMAIN",    "origin_oauth_redirect_url": "https://example.local",    "permission_scopes": "read write",    "allow_offline_access": false  }'

    The request returns a redirect URL.

    {  "redirect_url": "https://zis.zendesk.com/api/services/zis/connections/oauth/start_redirect?flow_token=xyz"}
  2. In a typical setup, the Zendesk app opens the redirect URL for the admin. If you're creating a connection without an app, open the redirect URL in a web browser.

    If you're not already logged in to Zendesk, the URL redirects you to the Zendesk sign-in page. Use this page to sign in to Zendesk.

  3. After you sign in, Zendesk redirects you to the origin_oauth_redirect_url from the Start OAuth Flow request. The URL now includes a verification_token query parameter. The parameter contains an OAuth verification code for Zendesk.

    If you used an origin_oauth_redirect_url of "https://example.local", the URL returns a browser error. This is expected and doesn't interfere with the creation of the connection. You can safely close the browser tab.

    Outside the browser, ZIS exchanges the verification code for a Zendesk OAuth access token. ZIS then stores the token in the "zendesk" connection.

  4. As an optional step, verify the "zendesk" connection using a Show OAuth Connection request.

    curl https://{subdomain}.zendesk.com/api/services/zis/connections/{integration}?name=zendesk \  -H "Authorization: Bearer {access_token}"

    The response contains information about the connection, including its access_token.

    {  "uuid": "***uuid***",  "name": "zendesk",  "zendesk_account_id": 12345678,  "integration": "example_zendesk_to_slack",  "permission_scope": "read write",  "access_token": "***access token***",  "token_type": "bearer",  "refresh_token": "",  "token_expiry": "0001-01-01T00:00:00Z",  "oauth_access_token_response_body": "",  "oauth_url_subdomain": "example",  "created_by": "1234567890123",  "created_at": "2099-05-16T15:33:19Z"}

Using a ZIS connection to authenticate API requests

Use the "$.connections.{connection_name}.access_token" reference path to use a connection's access token in a ZIS flow. Replace "{connection_name}" with the name of the connection.

For example, the following JSON defines a ZIS custom action. The action requires an OAuth access token to authenticate a Zendesk API request.

"zendesk.get_tickets": {  "type": "ZIS::Action::Http",  "properties": {    "name": "zendesk.get_tickets",    "definition": {      "method": "GET",      "path": "/api/v2/tickets.json",      "headers": [        {          "key": "Authorization",          "value": "Bearer {{$.access_token}}"        }      ]    }  }}

The following state calls the custom action in a ZIS flow. The state uses the "zendesk" connection's access token to authenticate the action's API request.

"Zendesk.GetTickets": {  "Type": "Action",  "ActionName": "zis:INTEGRATION:action:zendesk.get_tickets",  "Parameters": {    "access_token.$": "$.connections.zendesk.access_token"  },  "ResultPath": "$.retrievedTickets",  "Next": "NextState"}

Updating a ZIS connection

To update or replace an existing ZIS connection, make a Start OAuth Flow request using the same connection name. Then complete the OAuth flow using the same steps you took when creating the connection. Updating a ZIS connection doesn't change the OAuth client.

For example, the following request updates an existing connection named "slack". The request changes the connection's permission_scopes from "chat:write" to "chat:write:bot".

curl -X POST https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/start/{integration} \  -H "Authorization: Bearer {access_token}" \  -H 'content-type: application/json' \  -d '{    "name": "slack",    "oauth_client_name": "slack",    "origin_oauth_redirect_url": "https://example.local",    "permission_scopes": "chat:write:bot",    "allow_offline_access": false  }'