Skip to main content

Zendesk

Zendesk is a comprehensive customer service platform that provides ticketing, messaging, live chat, and help center solutions for customer support teams. With Zendesk Support, teams can manage customer inquiries across multiple channels, track ticket resolution, collaborate with internal notes, automate workflows with triggers and macros, and gain insights into support performance. It's designed to help support teams deliver exceptional customer experiences at scale.

Authentication Types​

Zendesk supports 2 authentication methods:

  • OAuth - Secure, app-based authentication with granular permission control through scopes.

    • Pros: Most secure, scope-based permissions, token expiration/refresh, user-specific access, production-ready, supports CORS for client-side requests
    • Cons: More complex setup, requires creating OAuth client in Zendesk Admin Center
    • Best for: Organizations with compliance requirements, production deployments, applications with multiple users, integrations requiring specific permission scopes

  • API Token - Simple, personal API token for quick integration.

    • Pros: Very simple setup, works immediately, no app registration needed, straightforward for single users
    • Cons: Basic authentication (being phased out by Zendesk), no scope limitations, one token per user, less secure for shared environments
    • Best for: Personal use, testing, quick prototypes, single-user scenarios, simple automations

General Settings​

Before using the connector, you need to configure:

  • Zendesk Subdomain - Your Zendesk subdomain (e.g., if your Zendesk URL is https://mycompany.zendesk.com, enter mycompany)
tip

You can find your subdomain in your Zendesk URL. It's the part before .zendesk.com. For example:

  • URL: https://acmecorp.zendesk.com → Subdomain: acmecorp
  • URL: https://support-team.zendesk.com → Subdomain: support-team

Setting up OAuth​

To use Zendesk with OAuth, you need to create an OAuth client in your Zendesk Admin Center.

1. Access Admin Center​

  1. Log in to your Zendesk account as an administrator

  2. Go to Admin Center

2. Navigate to OAuth Clients​

  1. In the Admin Center, go to Apps and integrations in the left sidebar

  2. Click on APIs

  3. Select the OAuth Clients tab

3. Create a New OAuth Client​

  1. Click Add OAuth client button

  2. Fill in the required fields:

    • Name - A descriptive name for your OAuth client
    • Description - Details about what this client will be used for
    • Company - Your company name
    • Identifier - This will be used as the client ID in Webrix
    • Client kind - Select Public
    • Redirect URLs - Add the callback URL provided from Webrix
    tip

    The redirect URL must exactly match what's provided by Webrix. Include the protocol (https://) and any trailing slashes.

  3. Click Save

  4. Copy the generated Secret - you'll need this for Webrix configuration

    warning

    The secret is shown only once. Copy it now and store it securely. If you lose it, you'll need to generate a new secret.

4. Configure in Webrix​

  1. In Webrix, create a new Zendesk MCP Server

  2. Under General Settings, enter your Zendesk Subdomain (e.g., mycompany)

  3. Under Authentication Type, select OAuth

  4. Paste your Client ID (Identifier)

  5. Paste your Client Secret

  6. Configure Scopes

    • read - Read access to all resources (tickets, users, organizations, etc.)
    • write - Write access to all resources
    • tickets:read - Read tickets only
    • tickets:write - Create and modify tickets
    • users:read - Read user information
    • users:write - Create and modify users
    • organizations:read - Read organization information
    • organizations:write - Create and modify organizations
    • hc:read - Read Help Center content
    • hc:write - Modify Help Center content
    tip

    Start with broader scopes like read and write for full functionality. You can refine to specific scopes like tickets:read for more restricted access.

  7. Click Save Changes

Setting up API Token​

API Token authentication is simpler but provides broader access. Use this for personal testing or single-user scenarios.

1. Generate an API Token​

  1. Log in to your Zendesk account

  2. Click on the Products icon in the sidebar (four squares icon)

  3. Select Admin Center

  4. Go to Apps and integrations → APIs → Zendesk API

  5. In the Settings tab, ensure Token Access is enabled

  6. Click the Add API token button (+ symbol)

  7. Enter a description for the token (e.g., "Webrix Integration" or "AI Assistant")

    tip

    Use descriptive names so you can identify tokens later. You can have up to 256 active tokens per account.

  8. Copy the generated API token immediately

    warning

    The token is shown only once. Copy it now and store it securely. If you lose it, you'll need to generate a new token. You cannot retrieve an existing token.

  9. Click Save

2. Find Your Email Address​

You'll need your Zendesk email address for API Token authentication:

  1. Click on your profile icon in the top right corner

  2. Your email address is displayed under your name

  3. Copy this email address

3. Configure in Your Integration Platform​

  1. In your integration platform, create a new Zendesk connection

  2. Under General Settings, enter your Zendesk Subdomain (e.g., mycompany)

  3. Under Authentication Type, select API Token or API Key

  4. Enter your Email Address (the one associated with your Zendesk account)

  5. Paste your API Token in the token field

  6. Click Save or Connect

4. Test the Connection​

  1. After saving, test the connection

  2. If successful, you should be able to access your Zendesk data

info

API Token authentication uses the format {email}/token:{api_token} which is automatically base64-encoded in the Authorization header as Basic authentication.

Troubleshooting​

Invalid Subdomain​

Cause: The subdomain entered doesn't match your Zendesk account.

Solution:

  1. Check your Zendesk URL in the browser
  2. Ensure you're entering only the subdomain part (e.g., mycompany, not mycompany.zendesk.com)
  3. Subdomain is case-sensitive in some cases - use the exact casing from your URL

OAuth Authorization Failed​

Cause: Redirect URL mismatch or client credentials are incorrect.

Solution:

  1. Verify the redirect URL in your OAuth client settings exactly matches what your integration platform provides
  2. Check that your Client ID and Secret are correct
  3. Ensure the OAuth client is active in Zendesk Admin Center
  4. Try generating a new Client Secret if the current one isn't working

Insufficient Permissions / 403 Forbidden​

Cause: The authenticated user doesn't have permission to perform the requested action, or required scopes are missing.

Solution:

For OAuth:

  1. Review the scopes selected in your OAuth client configuration
  2. Ensure you have read and write scopes, or specific scopes like tickets:write for the resources you're accessing
  3. Re-authorize the connection after updating scopes

For API Token:

  1. Verify that the user associated with the API token has the necessary role (agent or admin) to perform the action
  2. Check that the user has access to the specific tickets, users, or organizations you're trying to access
  3. Confirm that Token Access is enabled in Admin Center → Apps and integrations → APIs → Zendesk API

Rate Limiting / 429 Too Many Requests​

Cause: You've exceeded Zendesk's API rate limits.

Solution:

  1. Zendesk limits API requests per minute based on your plan
  2. Implement exponential backoff - wait before retrying
  3. Reduce the frequency of API calls
  4. Use bulk endpoints where available
  5. Check the Retry-After header in the 429 response for how long to wait
  6. Consider upgrading your Zendesk plan for higher rate limits

Cannot Modify Tags on Closed Tickets​

Cause: The Tags API endpoint doesn't allow modifications to closed tickets.

Solution:

  1. Use the "Update Ticket" tool instead, which can modify tags on closed tickets
  2. Alternatively, reopen the ticket, modify tags, then close it again
  3. This is a Zendesk API limitation documented in their API reference

API Token Not Working​

Cause: Token is expired, deleted, or Token Access is disabled.

Solution:

  1. Go to Admin Center → Apps and integrations → APIs → Zendesk API
  2. Verify that Token Access is enabled in Settings
  3. Check that your token appears in the Active API Tokens list
  4. If the token was deleted, generate a new one
  5. Ensure you're using the correct email address with the token
  6. Verify the email/token format: [email protected]/token:your_token_here

OAuth Scopes Changed / Need More Permissions​

Cause: Application needs additional permissions not originally requested.

Solution:

  1. Go to Admin Center → Apps and integrations → APIs → OAuth Clients
  2. Select your OAuth client
  3. Add the required scopes in the Scopes section
  4. Click Save
  5. In your integration platform, disconnect and reconnect to re-authorize with new scopes
  6. Users will need to re-authorize the application to grant the new permissions

Best Practices​

Security​

  • OAuth over API Token: Use OAuth for production applications as it provides better security through scopes and token expiration
  • Least Privilege: Only request the scopes you actually need (e.g., use tickets:read instead of read if you only need ticket access)
  • Token Rotation: Regularly rotate API tokens, especially if they're shared or exposed
  • Secure Storage: Never commit API tokens or OAuth secrets to version control

Performance​

  • Cursor Pagination: Use cursor-based pagination instead of offset pagination for better performance with large datasets
  • Rate Limits: Be aware of rate limits and implement retry logic with exponential backoff
  • Batch Operations: Use bulk endpoints when creating or updating multiple resources
  • Incremental Exports: For large data syncs, use the Incremental Ticket Export API instead of List Tickets

Data Management​

  • Search Wisely: The Search API is powerful but limited to 1,000 results - use specific filters to narrow results
  • Comment Limits: Tickets can have a maximum of 5,000 comments - plan accordingly for high-volume tickets
  • Custom Fields: Leverage custom fields for organization-specific data rather than workarounds
  • Tags for Organization: Use consistent tagging conventions for easy filtering and automation

Additional Resources​