Adding third-party OAuth to a Support app

In this tutorial, you'll create a private Zendesk Support app. The app uses an oauth setting to manage third-party OAuth access tokens.

A Zendesk admin can use the app to add tasks to their Todoist inbox from the Agent Workspace. When an admin installs the app, the oauth setting displays a related OAuth prompt.

The admin can use this prompt to create and store an OAuth access token for Todoist. The app uses the setting's access token to make Todoist REST API requests on the admin's behalf.

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk doesn't provide support for the app or the example code in this tutorial.

What you'll need

To complete this tutorial, you'll need the following:

• A Zendesk account with the Zendesk Suite Growth plan or above, or the Support Professional plan or above. To get a free eligible account for testing, see Getting a trial or sponsored account for development.

• The Zendesk Command Line Interface (ZCLI). To install or upgrade ZCLI, refer to Installing and updating ZCLI. You also need to authenticate ZCLI with your Zendesk account. See Authentication in the ZCLI documentation.

  ZCLI replaces the Zendesk Apps Tools (ZAT), which are in maintenance mode. To use ZAT instead, refer to Installing and using ZAT.

• Familiarity with the Zendesk Apps framework (ZAF) and the ZAF client's request() method. Before you start, complete the Building your first Support app tutorial and read Making API requests from a Zendesk app.

• Familiarity with basic OAuth 2.0 concepts, such as OAuth flows and access tokens. To learn more about OAuth, check out Using OAuth authentication with your application.

• A Todoist account. Todoist offers a Free plan. To create a Todoist account, see Create a Todoist account in Todoist help.

Creating the app files

First, create basic starter files for an app named Add Todoist tasks.

1. In your shell, navigate to the folder where you want to store the app. Example:

   cd projects

2. In the folder, run:

   zcli apps:new

3. At the prompts, enter the following values:

   • Directory name: add_todoist_tasks
   • Author's name: Your name
   • Author's email: Your email address
   • Author's website: Leave blank and press Enter.
   • App name: Add Todoist Tasks

   ZCLI creates app starter files in the add_todoist_tasks folder.

Setting up Todoist

To use the Todoist REST API, you first need to register a Todoist app. The app includes an OAuth client. For this tutorial, create a Todoist app named Add Zendesk Tasks.

1. Log in to Todoist and go to https://developer.todoist.com/appconsole.html. Click Create a new app.

   

2. On the Create App page, enter Add Zendesk Tasks as the app name. Leave App service URL blank. Click Create app.

   

3. Under App settings, enter "https://zis.zendesk.com/api/services/zis/connections/oauth/callback" as the OAuth redirect URL.

   

4. Click Save settings.

5. Save the client id and secret in a secure place. You'll use them later in the tutorial.

Adding an OAuth setting to the Zendesk app

Next, add an oauth setting to the Zendesk app's manifest.json file.

1. In manifest.json, add the following top-level oauth object. Replace CLIENT_ID and CLIENT_SECRET with the client id and secret from Setting up Todoist.

   {
     ...
     "oauth": {
       "client_id": "CLIENT_ID",
       "client_secret": "CLIENT_SECRET",
       "authorize_uri": "https://todoist.com/oauth/authorize",
       "access_token_uri": "https://todoist.com/oauth/access_token",
       "scope": "data:read_write"
     }
   }

2. In manifest.json, add the following top-level parameters property.

   {
     ...
     "parameters": [
       {
         "name": "token",
         "type": "oauth"
       }
     ],
     "oauth": {
       "client_id": "CLIENT_ID",
       "client_secret": "CLIENT_SECRET",
       "authorize_uri": "https://todoist.com/oauth/authorize",
       "access_token_uri": "https://todoist.com/oauth/access_token",
       "scope": "data:read_write"
     }
   }

3. Save manifest.json.

Adding the Zendesk app's code

Add the HTML and JavaScript for the app's iframe.

1. In the Zendesk app's assets folder, open iframe.html. Replace the file's contents with the following:

   <html>
     <body>
       <link
         rel="stylesheet"
         href="https://cdn.jsdelivr.net/combine/npm/@zendeskgarden/css-bedrock,npm/@zendeskgarden/css-buttons,npm/@zendeskgarden/css-forms,npm/@zendeskgarden/css-grid,npm/@zendeskgarden/css-utilities"
       />
       <form id="taskForm" class="container">
         <div class="row c-txt">
           <label for="task" class="col-12 c-txt__label">Task name</label>
           <textarea
             name="task"
             id="task"
             placeholder="Enter your task here"
             class="col-10 c-txt__input c-txt__input--area is-resizable"
           ></textarea>
         </div>
   
         <div class="row u-mt-sm">
           <button id="submitTask" class="c-btn c-btn--primary">Submit</button>
         </div>
       </form>
   
       <script src="https://static.zdassets.com/zendesk_app_framework_sdk/2.0/zaf_sdk.min.js"></script>
       <script type="text/javascript" src="main.js"></script>
     </body>
   </html>

   The HTML contains a form for submitting Todoist tasks. The HTML also loads the main.js script. You'll create main.js in the next step.

2. In the assets folder, create a main.js file. Paste the following JavaScript into the file.

   The code includes a call to the ZAF client's request() method. The request() call includes a {{setting.token}} placeholder for a stored Todoist access token. The call also uses a secure option of true.

   const client = ZAFClient.init();
   client.invoke("resize", { height: "155px" });
   
   document.getElementById("submitTask").addEventListener("click", (event) => {
     event.preventDefault();
     const task = {
       content: document.getElementById("task").value,
     };
   
     const options = {
       url: "https://api.todoist.com/rest/v2/tasks",
       type: "POST",
       headers: {
         Authorization: "Bearer {{setting.token}}",
       },
       contentType: "application/json",
       data: JSON.stringify(task),
       secure: true,
     };
   
     client.request(options).then(
       () => {
         document.getElementById("taskForm").reset();
         client.invoke("notify", "Task added to Todoist");
       },
       (error) => {
         var errorMsg = `Error ${error.status} ${error.statusText}`;
         client.invoke("notify", errorMsg, "error");
       }
     );
   });

   When an admin submits a task, the request() call makes an authenticated request to the Todoist REST API's Create a new task endpoint. ZAF routes the request through a Zendesk proxy server. The proxy server inserts the stored access token at the {{setting.token}} placeholder.

3. Save iframe.html and main.js.

Installing the app

ZCLI provides a local web server for app testing. However, the ZCLI server doesn't support secure settings, such as the oauth setting. As a workaround, use ZCLI to package and install the app to a test account instead.

1. In the add_todoist_tasks folder, run:

   zcli apps:create

   Leave the Add Todoist Tasks setting.token value prompt blank and press Enter.

   ZCLI packages, uploads, and installs the app to your Zendesk instance.

2. In Admin Center, click the Apps and integrations icon () in the sidebar. Then select Apps > Zendesk Support apps.

   The app appears in the list of currently installed apps on the My Apps page.

   

Starting an OAuth flow

Use the app's OAuth prompt to start and complete an OAuth flow with Todoist.

1. On the My Apps page, click the app icon to access the app's settings.

2. On the app's settings page, click Sign in with Add Todoist Tasks.

   

   This starts an OAuth flow with Todoist. Follow the prompts and click Agree on the Todoist OAuth page.

   

   When the flow completes, the OAuth Authentication section displays a check mark icon. ZAF stores the flow's access token outside the browser.

   

3. Click Update to reload the app.

Testing the app

Add a Todoist task to ensure the app works as intended.

1. Go to the Agent Workspace in Zendesk Support. From the workspace, open a new or existing ticket.

   The URL should look like this:

   https://{subdomain}.zendesk.com/agent/tickets/{ticket_id}

2. Click the Apps icon.

   

3. In the Add Todoist tasks app, enter a task in the Task Name field. Example: "Test my new Zendesk app".

   

4. Click Submit.

   A notification appears on the upper-right side of the Agent Workspace.

   

   After a few moments, the task appears in your Todoist inbox.