WIP: Add Zendesk Auth Provider docs

Author: EricGustin

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'

examples/code/integrations/zendesk/custom_auth.js

@@ -0,0 +1,183 @@
+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](#calling-zendesk-apis-directly) that needs to call Zendesk APIs
+- Or, your [custom tools](#create-your-own-zendesk-tools) that need to call Zendesk APIs
+
+## Create a Zendesk app
+
+To create a Zendesk app, there are two important guides from Zendesk that you can follow:
+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/)
+
+For a more streamlined set of instructions, follow the steps below:
+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 {8-12}
+
+```
+
+</Tabs.Tab>
+
+<Tabs.Tab>
+
+```javascript file=<rootDir>/examples/code/integrations/zendesk/custom_auth.js {8-10}
+
+```
+
+</Tabs.Tab>
+
+</Tabs>
+
+## Using Zendesk auth in custom tools
+
+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 {5-6,9-13,20}
+
+```