How to create a Zendesk OAuth app: A complete guide for 2026

If you're building an integration with Zendesk, you'll eventually need to authenticate your API requests. While API tokens work for simple scripts, OAuth is the standard for production applications that access Zendesk data on behalf of users. It lets users grant specific permissions without sharing their passwords, and it gives you fine-grained control over what your app can access.

But here's the thing: setting up OAuth can feel complicated if you've never done it before. There are redirects, authorization codes, scopes, and secrets to manage. This guide walks through the entire process step by step, from registering your app to making your first authenticated API call.

If you're looking for a simpler approach, eesel AI handles Zendesk authentication automatically. You connect your account once, and we manage the OAuth flow behind the scenes. But if you need to build a custom integration, keep reading.

What you'll need

Before you start, make sure you have:

• A Zendesk account on Suite Growth plan or above, or Support Professional plan or above
• Admin access to your Zendesk instance (or someone who can grant it)
• A basic understanding of OAuth 2.0 concepts (authorization codes, access tokens, redirects)
• A development environment where you can test the OAuth flow

If you're just experimenting, Zendesk offers trial accounts for development. You can also review the official Zendesk OAuth documentation for the latest details on authentication flows and endpoints.

Step 1: Register your OAuth client in Zendesk

The first step is telling Zendesk about your application. This creates an OAuth client that users authorize when they connect your app.

Navigate to the OAuth Clients section:

1. Sign in to Zendesk and go to the Admin Center (click the gear icon in the sidebar)
2. Select Apps and integrations in the left sidebar
3. Click APIs → OAuth Clients
4. Click Add OAuth client on the right side

Fill in the client details:

• Name: A display name for your app. Users see this when authorizing your app.
• Description: Optional, but helps users understand what your app does
• Company: Your company name
• Logo: Optional. Upload a square image (JPG, GIF, or PNG) that represents your app
• Client Kind: Choose between Public or Confidential
  • Confidential: For server-side apps where you can securely store the client secret
  • Public: For mobile apps or JavaScript applications where the secret could be exposed. These must use PKCE.
• Redirect URLs: The URLs where Zendesk will send users after they authorize your app. Must be HTTPS (except for localhost during development). Add multiple URLs on separate lines if needed.

Save your credentials:

After clicking Save, Zendesk generates a Client ID (called "Identifier") and Client Secret. Copy both immediately, the secret is only displayed once. If you lose it, you'll need to generate a new one.

Step 2: Choose the right OAuth flow

Zendesk supports two main OAuth 2.0 grant types. Pick the one that matches your use case.

Authorization code flow is for user-facing applications. When a user wants to connect your app to their Zendesk account, you redirect them to Zendesk's authorization page. They log in, approve the permissions, and Zendesk sends them back to your app with an authorization code. Your server exchanges this code for an access token.

This flow supports refresh tokens, so you can get new access tokens without asking the user to re-authorize. Access tokens expire (you can set this between 5 minutes and 2 days), but refresh tokens last longer (7 to 90 days).

Client credentials flow is for machine-to-machine authentication. There's no user involved. Your app uses its client ID and secret to get an access token directly. This works well for backend services that need to access Zendesk data on a schedule.

PKCE (Proof Key for Code Exchange) adds security for public clients. If you're building a mobile app or single-page application where you can't safely store a client secret, use PKCE with the authorization code flow. It prevents authorization code interception attacks.

Step 3: Configure OAuth scopes

Scopes control what your app can access in Zendesk. Be specific, requesting only the permissions you actually need follows the principle of least privilege and makes users more likely to trust your app.

Zendesk offers three main scope types:

• read: Access to GET endpoints. Includes permission to sideload related resources.
• write: Access to POST, PUT, and DELETE endpoints for creating, updating, and deleting resources.
• impersonate: Allows admins to make API requests on behalf of end users.

You can also request resource-specific scopes for finer control:

• tickets:read or tickets:write
• users:read or users:write
• organizations:read or organizations:write
• macros:read or macros:write
• triggers:read or triggers:write

For example, if your app only needs to read tickets and update user profiles, request tickets:read users:write instead of blanket read write access.

Important: A user's actual permissions in Zendesk still apply. Even if your OAuth scope allows writing tickets, a user with read-only access can't create tickets through your app.

Step 4: Implement the authorization flow

Here's how to implement the authorization code flow, the most common approach for web applications.

Send users to the authorization endpoint:

Redirect users to this URL with the required parameters:

https://{subdomain}.zendesk.com/oauth/authorizations/new

Include these query parameters:

• response_type=code (required)
• client_id={your_client_id} (required)
• redirect_uri={your_redirect_url} (required, must match what you registered)
• scope={requested_scopes} (required, space-separated)
• state={random_string} (recommended, prevents CSRF attacks)

Example URL:

https://yourcompany.zendesk.com/oauth/authorizations/new?response_type=code&client_id=your_client_id&redirect_uri=https://yourapp.com/callback&scope=read%20write&state=abc123

Handle the redirect:

After the user approves or denies access, Zendesk redirects them to your redirect_uri with either:

• An authorization code: ?code=7xqwtlf3rrdj8uyeb1yf&state=abc123
• An error: ?error=access_denied&error_description=User+denied+access

Verify the state parameter matches what you sent, then extract the code. Authorization codes expire after 120 seconds, so exchange them right away.

Exchange the code for tokens:

Make a POST request to Zendesk's token endpoint:

import requests

response = requests.post(
    f'https://{subdomain}.zendesk.com/oauth/tokens',
    data={
        'grant_type': 'authorization_code',
        'code': authorization_code,
        'client_id': client_id,
        'client_secret': client_secret,
        'redirect_uri': redirect_uri,
        'scope': 'read',
        'expires_in': 172800,  # 2 days
        'refresh_token_expires_in': 7776000  # 90 days
    }
)

tokens = response.json()
access_token = tokens['access_token']
refresh_token = tokens['refresh_token']

Store both tokens securely. The access token is what you'll use for API calls. The refresh token lets you get new access tokens when the current one expires.

Step 5: Use access tokens in API requests

With an access token, you can now make authenticated requests to the Zendesk API.

Include the token in the Authorization header:

Authorization: Bearer {access_token}

Example request:

import requests

headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get(
    f'https://{subdomain}.zendesk.com/api/v2/tickets.json',
    headers=headers
)

Handle token expiration:

When an access token expires, API requests return a 401 status with this error:

{
  "error": "invalid_token",
  "error_description": "The access token provided is expired, revoked, malformed or invalid for other reasons."
}

Use your refresh token to get a new access token:

response = requests.post(
    f'https://{subdomain}.zendesk.com/oauth/tokens',
    data={
        'grant_type': 'refresh_token',
        'refresh_token': refresh_token,
        'client_id': client_id,
        'client_secret': client_secret,
        'scope': 'read'
    }
)

new_tokens = response.json()

If the refresh token has also expired, you'll need to send the user through the authorization flow again.

Common issues and troubleshooting

"Invalid redirect URI" errors: The redirect URL in your authorization request must exactly match one of the URLs registered in your OAuth client. Check for trailing slashes, http vs https, and subdomain differences.

Scope permission denied: Remember that OAuth scopes are limited by the user's actual Zendesk permissions. An agent with read-only access can't write tickets even if your OAuth scope allows it.

Client secret only showing partially: Zendesk only displays the full secret once, immediately after creation. If you didn't copy it, you'll need to generate a new one in the OAuth client settings.

Testing with localhost: Zendesk allows http://localhost and http://127.0.0.1 as redirect URLs for development. Make sure you register the exact URL including the port (e.g., http://localhost:3000/callback).

Authorization code expired: Codes are only valid for 120 seconds. If your user takes too long to authorize, or if there's a delay in your code exchange, you'll get an error. Start the flow again.

Security best practices

Store secrets securely: Never hardcode client secrets in your source code or commit them to version control. Use environment variables or a secrets management service. The OWASP OAuth cheat sheet provides additional security recommendations for OAuth implementations.

Use HTTPS everywhere: All redirect URLs in production should use HTTPS. The only exception is localhost during development.

Implement PKCE for public clients: If you're building a mobile app or browser-based app where the secret could be exposed, use PKCE. Generate a code verifier, hash it to create a code challenge, and send the challenge with your authorization request.

Set reasonable token expiration: Shorter-lived tokens are more secure. For most applications, 24 hours is a good balance between security and convenience.

Rotate credentials regularly: Periodically generate new client secrets and update your applications. If you suspect a secret has been compromised, rotate it immediately.

Validate the state parameter: Always verify that the state parameter in the redirect matches what you sent. This prevents CSRF attacks where malicious sites trick users into authorizing unwanted access.

Skip the OAuth complexity with eesel AI

Building a custom OAuth integration takes time and ongoing maintenance. You need to handle the authorization flow, token refresh, error cases, and security updates. For many teams, this isn't the best use of engineering time.

eesel AI offers a simpler path. Our AI Agent connects to your Zendesk account with a single click. We handle the OAuth authentication automatically, so you can focus on what matters: building automations that actually solve problems.

Instead of writing code to exchange authorization codes and refresh tokens, you can:

• Train an AI on your help center articles and past tickets
• Set up automations that resolve tickets end-to-end
• Escalate complex issues to humans with plain English rules
• Run simulations on historical data before going live

If you're building a deeply custom integration, OAuth might be the right choice. But if you need AI-powered support automation without the engineering overhead, try eesel AI.