import { Tabs, Callout, Steps } from "nextra/components";
import { SignupLink } from "@/app/_components/analytics";

# Zendesk

<Callout type="info">
  Arcade does not offer a default Zendesk Auth Provider. To use Zendesk auth,
  you must create a [custom provider configuration](/references/auth-providers/oauth2)
  as described below.
</Callout>

The Zendesk auth provider enables tools and agents to call Zendesk APIs on behalf of a user.

## 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 MCP Server](/resources/integrations/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

<Callout type="info">
  When using your own app credentials, make sure you configure your project to
  use a [custom user
  verifier](/guides/user-facing-agents/secure-auth-production#build-a-custom-user-verifier).
  Without this, your end-users will not be able to use your app or agent in
  production.
</Callout>

### Additional guides

The following three 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/)
3. [Getting a trial or sponsored account for development](https://developer.zendesk.com/documentation/api-basics/getting-started/getting-a-trial-or-sponsored-account-for-development/)

### 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 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 the redirect URL generated by Arcade (see below) 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.
   - First, you will need to request a sponsored account and wait for approval from Zendesk. You can request a sponsored account [here](https://developer.zendesk.com/documentation/api-basics/getting-started/getting-a-trial-or-sponsored-account-for-development/#requesting-a-sponsored-test-account).
   - When filling out the sponsored account request form, ensure you select "App Developer / ISV" as your Developer Type.
   - After you have a sponsored account, 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



<Tabs items={["Dashboard GUI"]}>
<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)

Note the **Redirect URL** generated by Arcade. This must be set as your Zendesk app's redirect URL.

</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](/get-started/about-arcade) 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 {6-10}
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...
```

</Tabs.Tab>

<Tabs.Tab>

```javascript {8-11}
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...
```

</Tabs.Tab>

</Tabs>

## Using Zendesk auth in custom tools

If the [Arcade Zendesk MCP Server](/resources/integrations/customer-support/zendesk) does not meet your needs, you can author your own [custom tools](/guides/create-tools/tool-basics/build-mcp-server) 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
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}
```