Creating and managing OAuth connections

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

OAuth connections are a type of connection in the ZIS Connections Service. For more information about connections and other connection types, see Understanding connections.

Managing OAuth connections

You manage OAuth connections using the OAuth Clients and OAuth Connections endpoints of the Connections API.

In a typical setup, a developer first uses the Create OAuth Client endpoint to register an OAuth client for a system, such as Slack, in a ZIS integration. An admin then uses a private Zendesk app to connect the integration to the system. The app uses the OAuth Connections endpoints to start and complete an OAuth flow with the system. The app also handles any redirects and admin interactions required for the OAuth flow.

When the OAuth flow completes, the system sends ZIS an OAuth access token. ZIS stores this token in an OAuth connection in the ZIS Connections Service. You can then use the connection 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

OAuth connections support the following OAuth 2.0 grant types:

• Authorization code
• Client credentials

For OAuth connections created using an authorization code flow, ZIS also supports the refresh token grant type. See refreshing tokens from an authorization code flow.

You can't use an OAuth connection to store access tokens resulting from other grant types. To store such tokens, use a bearer token connection instead.

Creating an OAuth connection

This section contains instructions for creating an OAuth 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:

• A registered ZIS integration. See Registering the integration name.

• A ZIS OAuth access token for the integration. See Obtaining a ZIS OAuth token.

Note: The steps in Obtaining a ZIS OAuth token don't create an OAuth connection. Only use connections to authenticate API requests in a ZIS flow.

Creating an OAuth connection for a third-party system

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

After registering an OAuth client, you can use the OAuth Connections endpoints to start and complete an OAuth flow with the system. The steps for starting and completing the flow vary based on the grant type.

The steps for creating an OAuth connection for Zendesk differ from other systems. See Creating an OAuth connection for Zendesk.

Registering an OAuth client

To start, create and register an OAuth client.

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

2. Make a Create OAuth Client request to register the system's OAuth client in ZIS.

   For example, the following request creates an OAuth client for Slack. The client is named "slack". The client uses a default grant_type of "authorization_code".

   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",
       "grant_type": "authorization_code",
       "default_scopes": "chat:write",
       "auth_url": "https://slack.com/oauth/v2/authorize",
       "token_url": "https://slack.com/api/oauth.v2.access"
     }'

   As another example, the following request creates an OAuth client for Spotify. The client is named "spotify". The client uses a default grant_type of "client_credentials".

   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": "spotify",
       "client_id": "CLIENT_ID",
       "client_secret": "CLIENT_SECRET",
       "grant_type": "client_credentials",
       "token_url": "https://accounts.spotify.com/api/token"
     }'

Starting an authorization code flow

After registering a related OAuth client, you can use the OAuth Connections endpoints to start an OAuth flow with a third-party system using the authorization code grant type.

An authorization code flow requires direct interaction from a Zendesk admin. The admin must approve access to the third-party system using an OAuth authorization page.

1. Make a Start OAuth Flow request to start an OAuth flow with the system. Specify the name of a registered OAuth client for the system in oauth_client_name. For example, the following request creates an OAuth connection named "slack". The connection uses the "slack" OAuth client.

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

   If you're creating an OAuth 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 systems, 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",
       "grant_type": "authorization_code",
       "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"
   }

2. In a typical setup, the Zendesk app opens the redirect URL for the admin. If you're creating an OAuth connection without an app, open the redirect URL in a web browser. The URL redirects you to an OAuth authorization page for the system. Complete the authorization steps on the page.

3. After authorization, the system 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 system.

   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 system. If the request is successful, the system returns an access token response.

   ZIS stores the response's access token in an OAuth 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.

4. As an optional step, verify the new OAuth connection using a Show OAuth Connection request. The following request fetches an OAuth 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 tokens from an authorization code flow

If an OAuth connection created using an authorization code flow includes a refresh token, ZIS can automatically refresh the connection's access token using a refresh token flow. To enable automatic refreshes:

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

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

You can also force a refresh of an OAuth connection's access token using a Refresh OAuth Token request. For example, the following request forces a refresh for a connection named "hubspot".

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

Starting a client credentials flow

After registering a related OAuth client, you can use the OAuth Connections endpoints to start an OAuth flow with a third-party system using the client credentials grant type.

A client credentials flow is typically used for machine-to-machine authentication. The flow doesn't require interaction or approval from a Zendesk admin.

1. Make a Start OAuth Flow request to start an OAuth flow with the system. Specify the name of a registered OAuth client for the system in oauth_client_name. For example, the following request creates an OAuth connection named "spotify". The connection uses the "spotify" OAuth client.

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

   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": "spotify",
       "oauth_client_name": "spotify",
       "grant_type": "client_credentials"
     }'

   The request returns a URL for the Exchange Verification Code endpoint.

   {
     "redirect_url": "https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/access_codes/{integration}?verification_code=xyz"
   }

2. Use the URL to make an Exchange Verification Code request. Enclose the URL in quotes to escape any special characters.

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

   The response contains details about the OAuth connection, including its access token. Example:

   {
     "uuid": "***uuid***",
     "zendesk_account_id": 12345678,
     "integration": "INTEGRATION",
     "name": "spotify",
     "permission_scope": "",
     "access_token": "***access token***",
     "token_type": "Bearer",
     "refresh_token": "",
     "token_expiry": "2099-05-06T18:37:39Z",
     "oauth_access_token_response_body": "",
     "origin_oauth_redirect_url": "",
     "raw_callback_params": "",
     "created_by": "1234567890123"
   }

Renewing tokens from a client credentials flow

OAuth connections created using a client credentials flow may include a token_expiry date. When the token expires, ZIS automatically fetches a new access token by completing a client credentials flow using the same OAuth client.

You can also force the renewal of an OAuth connection's access token using a Refresh OAuth Token request. For example, the following request forces renewal for a connection named "spotify".

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

Creating an OAuth connection for Zendesk

The process for creating an OAuth connection for Zendesk is similar to the process for creating one for third-party systems. You complete an OAuth flow to create an access token, which ZIS then stores in your new connection.

Unlike third-party systems, however, you don't first have to manually create an OAuth client in Zendesk and then register it in ZIS. ZIS does this for you when you register your ZIS integration. ZIS names the OAuth client "zendesk". Use this client name in your OAuth flow.

The flow uses the authorization code grant type. The flow's resulting access token doesn't expire or use refresh tokens.

To create an OAuth connection for Zendesk

1. Start an OAuth flow with Zendesk by making a Start OAuth Flow request.

   In the request, specify a name and oauth_client_name of "zendesk". Specify your 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. Example:

   {
     "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 signed 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" OAuth connection.

4. As an optional step, verify the "zendesk" OAuth 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 an OAuth connection to authenticate API requests

To use an OAuth connection to authenticate API requests, see Using a connection to authenticate API requests in a ZIS flow.

Previously, you could also use the $.connections.{oauth_connection_name}.access_token reference path to access an OAuth connection's access token in an action state. This reference path is deprecated and may be removed in a future release.

Updating an OAuth connection

To update or replace an existing OAuth 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 an OAuth connection doesn't change the OAuth client.

For example, the following request updates an existing OAuth connection named "slack".

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
  }'