Add Zendesk Auth Provider docs (#354)

EricGustin · web-flow · commit 7fbb1e421742 · 2025-07-18T14:43:46.000-07:00
* WIP: Add Zendesk Auth Provider docs

* Finish writing Zendesk auth provider docs

* Add test to Makefile
diff --git a/Makefile b/Makefile
@@ -12,6 +12,21 @@ install: ## Install the dependencies
 build: ## Build the docs site
 	@pnpm build
 
+test: ## Run the tests
+	@pnpm test -- --run
 
 run: ## Run the docs site locally
 	@pnpm dev
+
+ruin:
+	@echo "\033[31m\033[1m💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️\033[0m"
+	@echo "\033[31m\033[1m👻                                          👻\033[0m"
+	@echo "\033[31m\033[1m🔥  With but a single command, the realm   🔥\033[0m"
+	@echo "\033[31m\033[1m🔥  of order shall collapse into chaos.    🔥\033[0m"
+	@echo "\033[31m\033[1m👻                                          👻\033[0m"
+	@echo "\033[31m\033[1m⚡  Beware, for what is ruined today may   ⚡\033[0m"
+	@echo "\033[31m\033[1m⚡  take an eternity to rebuild.           ⚡\033[0m"
+	@echo "\033[31m\033[1m👻                                          👻\033[0m"
+	@echo "\033[31m\033[1m🎃      - The Elders of Makefile           🎃\033[0m"
+	@echo "\033[31m\033[1m👻                                          👻\033[0m"
+	@echo "\033[31m\033[1m💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️\033[0m"
diff --git a/examples/code/integrations/zendesk/config_provider.engine.yaml b/examples/code/integrations/zendesk/config_provider.engine.yaml
@@ -0,0 +1,43 @@
+auth:
+  providers:
+    - id: zendesk
+      description: "Custom Zendesk provider"
+      enabled: true
+      type: oauth2
+      client_id: ${env:ZENDESK_CLIENT_ID}
+      oauth2:
+        scope_delimiter: ' '
+        pkce:
+          enabled: true
+          code_challenge_method: S256
+        authorize_request:
+          endpoint: 'https://<your-zendesk-subdomain>.zendesk.com/oauth/authorizations/new'
+          params:
+            client_id: '{{client_id}}'
+            redirect_uri: '{{redirect_uri}}'
+            scope: '{{scopes}} {{existing_scopes}}'
+            response_type: code
+        token_request:
+          endpoint: 'https://<your-zendesk-subdomain>.zendesk.com/oauth/tokens'
+          params:
+            grant_type: authorization_code
+            client_id: '{{client_id}}'
+            redirect_uri: '{{redirect_uri}}'
+          response_content_type: application/json
+          response_map:
+            access_token: '$.access_token'
+            refresh_token: '$.refresh_token'
+            expires_in: '$.expires_in'
+            scope: '$.scope'
+        refresh_request:
+          endpoint: 'https://<your-zendesk-subdomain>.zendesk.com/oauth/tokens'
+          params:
+            grant_type: refresh_token
+            refresh_token: '{{refresh_token}}'
+            client_id: '{{client_id}}'
+          response_content_type: application/json
+          response_map:
+            access_token: '$.access_token'
+            refresh_token: '$.refresh_token'
+            expires_in: '$.expires_in'
+            scope: '$.scope'
diff --git a/examples/code/integrations/zendesk/custom_auth.js b/examples/code/integrations/zendesk/custom_auth.js
@@ -0,0 +1,23 @@
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
+
+const userId = "{arcade_user_id}";
+
+// Start the authorization process
+let authResponse = await client.auth.start(userId, {
+  provider: "zendesk",
+  scopes: ["read_account"],
+});
+
+if (authResponse.status !== "completed") {
+  console.log("Please complete the authorization challenge in your browser:");
+  console.log(authResponse.url);
+}
+
+// Wait for the authorization to complete
+authResponse = await client.auth.waitForCompletion(authResponse);
+
+const token = authResponse.context.token;
+
+// Do something interesting with the token...
diff --git a/examples/code/integrations/zendesk/custom_auth.py b/examples/code/integrations/zendesk/custom_auth.py
@@ -0,0 +1,21 @@
+from arcadepy import Arcade
+
+client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
+
+# Start the authorization process
+auth_response = client.auth.start(
+    user_id="{arcade_user_id}",
+    provider="zendesk",
+    scopes=["read_account"],
+)
+
+if auth_response.status != "completed":
+    print("Please complete the authorization challenge in your browser:")
+    print(auth_response.url)
+
+# Wait for the authorization to complete
+auth_response = client.auth.wait_for_completion(auth_response)
+
+token = auth_response.context.token
+
+# Do something interesting with the token...
diff --git a/examples/code/integrations/zendesk/custom_tool.py b/examples/code/integrations/zendesk/custom_tool.py
@@ -0,0 +1,31 @@
+from typing import Annotated, Any
+
+from arcade_tdk import ToolContext, tool
+from arcade_tdk.auth import OAuth2
+
+import httpx
+
+
+@tool(
+  requires_auth=OAuth2(id="zendesk", scopes=["read"]),
+  requires_secrets=["ZENDESK_SUBDOMAIN"],
+)
+async def get_tickets(
+  context: ToolContext
+) -> Annotated[dict[str, Any], "Recent tickets from Zendesk"]:
+    """Get recent tickets from Zendesk including basic ticket information"""
+    token = context.get_auth_token_or_empty()
+    subdomain = context.get_secret("ZENDESK_SUBDOMAIN")
+    url = f"https://{subdomain}.zendesk.com/api/v2/tickets.json"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(url, headers=headers)
+        resp.raise_for_status()
+        data = resp.json()
+
+        return {"tickets": data}
diff --git a/pages/home/auth-providers/zendesk.mdx b/pages/home/auth-providers/zendesk.mdx
@@ -0,0 +1,184 @@
+import { Tabs } from "nextra/components";
+import { SignupLink } from "@/components/Analytics";
+
+# Zendesk Auth Provider
+
+<Note>
+  Arcade does not offer a default Zendesk Auth Provider. To use Zendesk auth, you must create
+  a [custom provider configuration](/home/auth-providers/oauth2) as described below.
+</Note>
+
+The Zendesk auth provider enables tools and agents to call Zendesk APIs on behalf of a user. Behind the scenes, the Arcade Engine and the Zendesk auth provider seamlessly manage Zendesk OAuth 2.0 authorization for your users.
+
+## What's documented here
+
+This page describes how to use and configure Zendesk auth with Arcade.
+
+This auth provider is used by:
+
+- The [Arcade Zendesk toolkit](/toolkits/customer-support/zendesk), which provides pre-built tools for interacting with Zendesk services
+- Your [app code](#using-zendesk-auth-in-app-code) that needs to call Zendesk APIs
+- Or, your [custom tools](#using-zendesk-auth-in-custom-tools) that need to call Zendesk APIs
+
+## Create a Zendesk app
+
+### Additional guides
+The following two guides from Zendesk will be helpful additional information as you progress through this guide:
+1. [Using OAuth authentication with your application](https://support.zendesk.com/hc/en-us/articles/4408845965210-Using-OAuth-authentication-with-your-application)
+2. [Set up a global OAuth client](https://developer.zendesk.com/documentation/marketplace/building-a-marketplace-app/set-up-a-global-oauth-client/)
+
+### Creating a Zendesk app for Arcade
+1. Create your Organization in the [Zendesk Marketplace portal](https://apps.zendesk.com/).
+1. Create a Zendesk support account at https://www.zendesk.com/login . If you need a global OAuth client, then the subdomain MUST begin with "d3v-". You will need a global OAuth client if your app will use integrations/tools for multiple customers with their own Zendesk instances (multiple subdomains).
+1. In [the Admin Center](https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb), click "Apps and integrations" in the sidebar, then select APIs > OAuth clients > Add OAuth client.
+    * Ensure your identifier is prefixed with "zdg-" If you will need a global OAuth client.
+    * Select "Public" for "Client kind".
+    * Use `https://cloud.arcade.dev/api/v1/oauth/callback` as your "Redirect URL".
+1. Copy and store your identifier for later. This will be your **Client ID**.
+1. Copy and store your generated secret for later. This will be your **Client Secret**.
+1. (Only for Global OAuth client) Request a global OAuth client.
+    * Sign into the [Zendesk Marketplace portal](https://apps.zendesk.com/)
+    * Organization > Global OAuth Request and fill out the form. Zendesk will typically review your request within 1 week.
+
+
+
+## Get your Zendesk subdomain
+
+Your Zendesk subdomain is the value before the `.zendesk.com` part. For example, if your Zendesk domain is `https://d3v-acme-inc.zendesk.com`, your Zendesk subdomain is `d3v-acme-inc`. Take note of your Zendesk subdomain. You will need this value in the next steps.
+
+## Set the Zendesk Subdomain Secret
+
+Set the `ZENDESK_SUBDOMAIN` secret in the [Arcade Dashboard](https://api.arcade.dev/dashboard/auth/secrets).
+
+## Configuring Zendesk Auth
+
+You can either configure Zendesk auth from the Arcade Dashboard or in the `engine.yaml` file if you are running the Engine yourself. We describe both options below.
+
+<Tabs items={["Dashboard GUI", "Engine Configuration YAML"]}>
+<Tabs.Tab>
+
+### Configure Zendesk Auth Using the Arcade Dashboard GUI
+
+<Steps>
+
+#### Access the Arcade Dashboard
+
+Navigate to the [Arcade Dashboard](https://api.arcade.dev/dashboard/auth/oauth) OAuth Providers page.
+
+#### Navigate to the Add Custom Provider page
+
+- Click **Add OAuth Provider** in the top right corner.
+- Click the **Custom Provider** tab at the top.
+
+#### Enter the provider details
+
+- ID: `zendesk`
+- Description: `<your description>`
+- Client ID: `<your identifier>` (This is prefixed with `zdg-` if you are using a global OAuth client)
+- Client Secret: `<your client secret>`
+- Authorization Endpoint: `https://<your-zendesk-subdomain>.zendesk.com/oauth/authorizations/new`
+- Token Endpoint: `https://<your-zendesk-subdomain>.zendesk.com/oauth/tokens`
+- PKCE Settings:
+  - Enable PKCE: `enabled`
+  - PKCE Method: `S256` (Default)
+- Authorization Settings:
+  - Response Type: `code` (Default)
+  - Scope: `{{scopes}} {{existing_scopes}}` (Default)
+- Token Settings:
+  - Authentication Method: `Client Secret Basic` (Default)
+  - Response Content Type: `application/json` (Default)
+- Refresh Token Settings:
+  - Refresh Token Endpoint: `https://<your-zendesk-subdomain>.zendesk.com/oauth/tokens`
+  - Authentication Method: `Client Secret Basic` (Default)
+  - Response Content Type: `application/json`
+- Token Introspection Settings:
+  - Enable Token Introspection: `disabled` (Default)
+
+</Steps>
+</Tabs.Tab>
+
+<Tabs.Tab>
+
+### Configure Zendesk Auth Using the Engine Configuration YAML
+
+<Tip>
+  Refer to [Engine configuration](/home/local-deployment/configure/engine) for more information on how to set environment variables and configure the Arcade Engine.
+</Tip>
+
+<Tip>
+  To find where the `engine.yaml` file is located in your OS after installing the Arcade Engine, check the [Engine configuration file](/home/local-deployment/configure/overview#engine-configuration-file) documentation.
+</Tip>
+
+<Steps>
+
+#### Set environment variables
+
+Set the following environment variables:
+
+```bash
+export ZENDESK_CLIENT_ID="<your client ID>"
+export ZENDESK_CLIENT_SECRET="<your client secret>"
+```
+
+Or, you can set these values in a `.env` file:
+
+```bash
+ZENDESK_CLIENT_ID="<your client ID>"
+ZENDESK_CLIENT_SECRET="<your client secret>"
+```
+
+#### Edit the Engine configuration
+
+<Note>
+  In the YAML code demonstrated below, replace `<your-zendesk-subdomain>` in the endpoint URLs with your Zendesk subdomain.
+</Note>
+
+Edit the `engine.yaml` file by adding a Zendesk item to the `auth.providers` section:
+
+```yaml file=<rootDir>/examples/code/integrations/zendesk/config_provider.engine.yaml {3-43}
+
+```
+
+#### Restart the Arcade Engine
+
+If the Arcade Engine is already running, you will need to restart it for the changes to take effect.
+
+</Steps>
+</Tabs.Tab>
+
+</Tabs>
+
+## Using Zendesk auth in app code
+
+Use the Zendesk auth provider you just created in your own agents and AI apps to get a user token for Zendesk APIs. See [authorizing agents with Arcade](/home/auth/how-arcade-helps) to understand how this works.
+
+Use `client.auth.start()` to get a user token for Zendesk APIs:
+
+<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
+<Tabs.Tab>
+
+```python file=<rootDir>/examples/code/integrations/zendesk/custom_auth.py {6-10}
+
+```
+
+</Tabs.Tab>
+
+<Tabs.Tab>
+
+```javascript file=<rootDir>/examples/code/integrations/zendesk/custom_auth.js {8-11}
+
+```
+
+</Tabs.Tab>
+
+</Tabs>
+
+## Using Zendesk auth in custom tools
+
+If the [Arcade Zendesk toolkit](/toolkits/customer-support/zendesk) does not meet your needs, you can author your own [custom tools](/home/build-tools/create-a-toolkit) that interact with Zendesk APIs.
+
+Use the `OAuth2()` auth class to specify that a tool requires authorization with Zendesk. The `context.authorization.token` field will be automatically populated with the user's Zendesk token:
+
+```python file=<rootDir>/examples/code/integrations/zendesk/custom_tool.py
+
+```
