Zendesk Auth Provider

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, which provides pre-built tools for interacting with Zendesk services
• Your app code that needs to call Zendesk APIs
• Or, your 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
2. Set up a global OAuth client

Creating a Zendesk app for Arcade

1. Create your Organization in the Zendesk Marketplace portal.
2. 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).
3. In the Admin Center, 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”.
4. Copy and store your identifier for later. This will be your Client ID.
5. Copy and store your generated secret for later. This will be your Client Secret.
6. (Only for Global OAuth client) Request a global OAuth client.
   • Sign into the Zendesk Marketplace portal
   • 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.

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.

export ZENDESK_CLIENT_ID="<your client ID>"
export ZENDESK_CLIENT_SECRET="<your client secret>"

ZENDESK_CLIENT_ID="<your client ID>"
ZENDESK_CLIENT_SECRET="<your client secret>"

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'

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 to understand how this works.

Use client.auth.start() to get a user token for Zendesk APIs:

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...

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...

Using Zendesk auth in custom tools

If the Arcade Zendesk toolkit does not meet your needs, you can author your own custom tools 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:

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}