# Zendesk: OAuth app setup and approval Reviewed · Sourced · updated 27 Oct 2026 · https://oauth-guide.akshatsethi.com/apps/zendesk > You can create a local OAuth client and connect your own Zendesk instance in under an hour, but that client only works on one subdomain. To let other Zendesk customers connect, Zendesk has to approve a global OAuth client, and since August 2025 your integration must also go through Marketplace review (1 to 3 weeks for new submissions), even if it won't be listed publicly. - **Your hands-on work:** 4–10 h - **Waiting on Zendesk:** Unknown - **First user can connect:** Today, in about 30 minutes, on your own Zendesk subdomain using a local OAuth client - **Why Reviewed:** Third-party integrations must use a Zendesk-approved global OAuth client and pass Marketplace review. Local clients only work on one instance, and you're not allowed to use a customer's own OAuth client or API token. - **Using Composio?** Composio lists a managed Zendesk OAuth app, so you can prototype without registering your own client. To ship under your own name and meet Zendesk's Marketplace rules (approved global client plus marketplace headers), register your own global client before launch. ## Path to launch ### Build: Your instance - Who can connect: Only users on the single Zendesk subdomain where you created the local OAuth client - What users see: The Zendesk authorization page on your subdomain, showing your client name, logo and requested scopes - Effort: 20–45 min · Wait: None - Next: Zendesk approves your global OAuth request and accepts your Marketplace integration submission - _(Docs [4, 5])_ ### Launch: Any Zendesk customer - Who can connect: Admins and users on any Zendesk subdomain - What users see: The Zendesk authorization page on their own subdomain, listing only the scopes Zendesk allowed for your global client - Effort: 4–10 h · Wait: Unknown - _(Docs [1, 7, 9, 11])_ ## Before you start - [ ] **Zendesk account with admin access** (You). You need admin rights in Admin Center to create OAuth clients. A free 14-day Support trial works for building. _(Docs [4, 3])_ - [ ] **Sponsored developer account with a d3v- subdomain** (You). Global OAuth requests are only accepted from subdomains that start with d3v-. You get one by renaming a trial subdomain and filling in Zendesk's Sponsored Account Request Form. It's free, covers 5 agents, and must not be used for real support. _(Docs [1, 3])_ - [ ] **Organization registered on the Marketplace portal** (You). Register your organization at apps.zendesk.com. You need it to request a global client, to claim it, to submit the app, and to get the organization ID header value. _(Docs [9, 10, 11])_ - [ ] **Privacy notice** (You). Under the Zendesk Developer Terms, you must publish a privacy notice that discloses what data your integration accesses, uses and stores, and why. _(Docs [14], medium confidence)_ - [ ] **HTTPS redirect URI** (Agent). Redirect URLs must be absolute and use HTTPS. The only exceptions are localhost and 127.0.0.1. _(Docs [5])_ ## Steps 1. **Create a local OAuth client in Admin Center** (Agent, 10–20 min). In Admin Center, go to Apps and integrations > APIs > OAuth clients and click Add OAuth client. If you'll request a global client later, do this on your d3v- account and fill in every field. _(Docs [5, 1, 6])_ - Name: your product name (users see it on the consent page) - Description, Company, Logo (JPG/GIF/PNG): fill these in, because they're mandatory for global requests - Identifier: prefix it with zdg- (for example zdg-yourproduct). This becomes your client_id - Client kind: Confidential for a backend that holds a secret, or Public if you use PKCE only - Redirect URLs: your redirect URI, one per line - Scopes: list only what you need (for example tickets:read tickets:write), or leave empty to allow all - Click Save - Agent: An agent can fill the form once an admin is signed in. Stop before the secret appears after Save and hand off to a person. - Watch out: A local client works only on the subdomain where you created it. Every authorization and token URL includes the user's subdomain. 2. **Copy the client secret and store it securely** (You, 2–5 min). After the first Save, a Secret field appears. Zendesk shows the full secret only once and later shows only the first nine characters. Copy it into your secrets store and click Save again. _(Docs [5, 1, 10])_ - Copy the secret into your secret manager - Click Save again to finish - Agent: A person must handle the secret. - Watch out: Keep the secret. Once the client becomes global, you lose access to its admin page, and you'll need the first 6 characters of the secret to claim the client. 3. **Configure your OAuth client and test a connection** (Agent, 10–20 min). Point your OAuth client at https://{subdomain}.zendesk.com/oauth/authorizations/new and https://{subdomain}.zendesk.com/oauth/tokens. Ask each user for their subdomain before you start the flow. Support refresh tokens: access tokens last 30 minutes and refresh tokens 30 days by default, and each refresh rotates both. _(Docs [5, 8])_ - Set the authorization URL to https://{subdomain}.zendesk.com/oauth/authorizations/new with response_type=code, client_id, redirect_uri, scope and state - Set the token URL to https://{subdomain}.zendesk.com/oauth/tokens (grant_type=authorization_code, then refresh_token) - For PKCE, send code_challenge with code_challenge_method=S256, then send code_verifier - Exchange the code within 120 seconds - Connect your own instance and make a test API call - Agent: An agent can enter the endpoints, client_id and redirect URI and run the test. A person enters the secret. - Watch out: Refreshing invalidates the previous access and refresh tokens. Store the new pair every time, or users will have to authorize again. 4. **Get a sponsored d3v- developer account** (You, 15–30 min). Start a Zendesk Support trial, rename the subdomain so it starts with d3v-, and submit the Sponsored Account Request Form. Zendesk emails you when the trial is converted. _(Docs [3])_ - Sign up at zendesk.com/register/free-trial - Rename the subdomain with the d3v- prefix - Submit the form at https://forms.gle/NDkrqK9xkZrnWoyk9 - Agent: A person must sign up and submit the form. - Watch out: Zendesk suspends sponsored accounts that are used for real customer support. 5. **Wait for sponsored account conversion** (Provider, wait Unknown). Zendesk converts the trial to a sponsored account and notifies you. The docs don't give a timeline. _(Docs [3], medium confidence)_ - Watch out: A trial expires after 14 days, so submit the form early. 6. **Register your organization on the Marketplace portal** (You, 15–30 min). Sign in at apps.zendesk.com and register your organization. Your organization ID, shown at the top of the Organization page, is the value for the X-Zendesk-Marketplace-Organization-Id header. _(Docs [9, 11])_ - Sign in at apps.zendesk.com - Register the organization and accept the developer terms - Note the organization ID - Agent: A person must accept the terms. An agent can then read off the organization ID. 7. **Request a global OAuth client** (You, 15–30 min). In the Marketplace portal, choose Global OAuth > Request new OAuth. The d3v- subdomain and zdg- identifier are prefilled; check that they match your local client and request only the scopes you need. _(Docs [1, 6])_ - Open Global OAuth in the left menu - Click Request new OAuth - Confirm the d3v- subdomain and zdg- identifier - List the minimum scopes - Submit, then add support@appsubmission.zendesk.com to your contacts - Agent: An agent can fill the form. A person should review the scopes and submit. - Watch out: Zendesk rejects requests from subdomains without the d3v- prefix, and requests where the local client's optional fields are blank. - Screenshot: ![Global OAuth request form in the Zendesk Marketplace portal](https://zen-marketing-documentation.s3.amazonaws.com/docs/en/request_new_outh_form.png) [1] 8. **Wait for global OAuth approval** (Provider, wait Unknown). You get an email and a ticket reference. If Zendesk approves, it converts your local client into a global client, possibly with a restricted set of allowed scopes. The docs give no timeframe. _(Docs [1])_ - Watch out: After conversion, only Zendesk's Marketplace Operations team can edit the client. To change scopes, contact Zendesk Support and mention "global oauth allowed scopes" and your client_id. 9. **Claim the global client in the portal** (You, 5–10 min). In the Global OAuth section, click Claim Global Auth. Enter the client_id and the first 6 characters of the client secret so the client is linked to your organization. _(Docs [10])_ - Click Claim Global Auth - Enter the OAuth identifier and the first 6 characters of the secret - Click Claim - Agent: Part of the secret is involved, so a person should do this. - Screenshot: ![Claim a global OAuth client dialog](https://zen-marketing-documentation.s3.amazonaws.com/docs/en/claim_new_global_oauth_client.png) [10] 10. **Submit your integration app to the Marketplace** (You, 2–6 h). Submit an integration app: a ZIP with marketing assets, translations and a manifest that sets "marketingOnly": true. On the Compliance tab, answer Yes to using a global OAuth client and select your claimed client. Designate a test account where Zendesk can verify your headers. _(Docs [9, 10, 7])_ - Prepare the ZIP with manifest (marketingOnly: true), translations and assets - Fill in the listing, including a privacy policy URL - On Compliance, answer Yes to the global OAuth question and select your client - Designate a test account for header verification - Agent: An agent can prepare the assets and fill in the fields. A person must submit. - Watch out: Integrations that aren't publicly listed must also create a Marketplace profile and submit. - Screenshot: ![App submission compliance questions including global OAuth client selection](https://zen-marketing-documentation.s3.amazonaws.com/docs/en/app-submission-compliance.png) [10] 11. **Add the Marketplace headers to API calls** (Agent, 30–60 min). Send X-Zendesk-Marketplace-Name, X-Zendesk-Marketplace-Organization-Id and X-Zendesk-Marketplace-App-Id on every Zendesk API request your servers make. Zendesk assigns the app ID when you submit, so update your code then. _(Docs [11, 9])_ - Add the three headers to your API request code - Make calls against the designated test account so Zendesk can see the headers - Agent: An agent can update the request configuration and run test calls. - Watch out: Zendesk won't approve the app until it sees these headers on your test account. 12. **Wait for Marketplace review** (Provider, wait 1–3 weeks). Zendesk says new submissions take 1 to 3 weeks and updates take 1 to 2 weeks. _(Docs [9])_ ## Scopes Zendesk doesn't classify scopes as sensitive or restricted. For a global client, Zendesk may cap the allowed scopes when it approves your request. Requesting a scope outside that list fails with invalid_scope. | Scope | Grants | Level | Consequence | |---|---|---|---| | `read / write` | Read or write access to all resources | basic | Zendesk reviews these as part of the global OAuth request, which asks for the minimum scopes your app needs | | `resource:read / resource:write (for example tickets:read)` | Access to a single resource type | basic | Nothing extra. These are preferred for a narrow request | | `impersonate` | Lets admins act on behalf of end users | sensitive | No separate process is documented. It's listed in the global request like any other scope (inferred) | ## When you get stuck - **Global OAuth request is rejected or not accepted.** The request was submitted from a subdomain without the d3v- prefix, or the local client's identifier lacks zdg- or has empty optional fields Fix: Get a sponsored d3v- account, recreate the local client with a zdg- identifier and every field filled in, then resubmit _(Docs [1, 6])_ - **OAuth fails for customers on other subdomains.** Local OAuth clients only exist on the instance where they were created Fix: Use an approved global OAuth client. Don't ask customers to create their own clients or API tokens, which Zendesk prohibits for third parties _(Docs [4, 7])_ - **400 Bad Request with invalid_scope.** Your app requested a scope outside the allowed scopes Zendesk set on the global client Fix: Request only allowed scopes, or contact Zendesk Support about "global oauth allowed scopes" with your client_id _(Docs [1])_ - **401 invalid_token after about 30 minutes.** Access tokens expire by default: refresh tokens are required for global clients since February 2, 2026, and default expiry applies to local clients created after April 30, 2026 Fix: Implement the refresh_token grant and store the rotated tokens each time _(Docs [8, 5])_ - **Marketplace submission stalls.** Zendesk doesn't see the X-Zendesk-Marketplace-* headers on the designated test account Fix: Add all three headers once the app ID is assigned and make API calls against the test account _(Docs [11])_ ## Not confirmed yet - **How long does global OAuth client approval take?** Zendesk's docs and third-party guides give no timeframe, and no community reports turned up To resolve: Watch the ticket Zendesk sends after you submit, or ask in Zendesk's developer community - **How long does sponsored account conversion take?** The docs only say Zendesk will notify you To resolve: Submit the form early, while your trial still has time left - **Must the global OAuth request be approved before you submit the Marketplace app, or can they run in parallel?** The docs describe both steps but don't say which order is required To resolve: Ask Marketplace Operations in the global OAuth ticket - **What exactly is required for an unlisted (private distribution) integration?** The developer update says unlisted integrations must submit, but no page details how unlisted listings work To resolve: Check the Marketplace portal submission options or ask Zendesk partner support ## Sources 1. [Set up a global OAuth client](https://developer.zendesk.com/documentation/marketplace/building-a-marketplace-app/set-up-a-global-oauth-client/) (Zendesk Developer Docs). Checked 27 Oct 2026 2. [Composio managed auth toolkits](https://docs.composio.dev/toolkits/managed-auth.md) (Composio docs). Checked 27 Oct 2026 3. [Getting a trial or sponsored account for development](https://developer.zendesk.com/documentation/developer-tools/getting-started/getting-a-trial-or-sponsored-account-for-development/) (Zendesk Developer Docs). Checked 27 Oct 2026 4. [Creating and using OAuth tokens with the API](https://developer.zendesk.com/documentation/ticketing/working-with-oauth/creating-and-using-oauth-tokens-with-the-api/) (Zendesk Developer Docs). Checked 27 Oct 2026 5. [Using OAuth authentication with your application](https://support.zendesk.com/hc/en-us/articles/4408845965210-Using-OAuth-authentication-with-your-application) (Zendesk Help Center). Checked 27 Oct 2026 6. [How to register your own Zendesk API OAuth app](https://www.nango.dev/docs/api-integrations/zendesk/how-to-register-your-own-zendesk-api-oauth-app) (Nango docs). Checked 27 Oct 2026 7. [Developer update: Enhanced security guidelines for third-party apps, integrations, and bots](https://support.zendesk.com/hc/en-us/articles/9590471542170-Developer-update-Enhanced-security-guidelines-for-third-party-apps-integrations-and-bots) (Zendesk Help Center). Checked 27 Oct 2026 8. [Announcing the required expiration of global OAuth access and refresh tokens](https://support.zendesk.com/hc/en-us/articles/10212201463962-Announcing-the-required-expiration-of-global-OAuth-access-and-refresh-tokens) (Zendesk Help Center). Checked 27 Oct 2026 9. [Submit your app](https://developer.zendesk.com/documentation/marketplace/publishing-to-the-marketplace/submit-your-app/) (Zendesk Developer Docs). Checked 27 Oct 2026 10. [Managing global OAuth clients and app associations](https://developer.zendesk.com/documentation/apps/app-developer-guide/managing-global-oauth-clients-and-app-associations/) (Zendesk Developer Docs). Checked 27 Oct 2026 11. [Request header requirements for Marketplace apps](https://developer.zendesk.com/documentation/marketplace/building-a-marketplace-app/request-header-requirements-for-marketplace-apps) (Zendesk Developer Docs). Checked 27 Oct 2026 12. [Announcing enhanced security guidelines for third-party apps, integrations, and bots](https://support.zendesk.com/hc/en-us/articles/9561388533018-Announcing-enhanced-security-guidelines-for-third-party-apps-integrations-and-bots) (Zendesk Help Center). Checked 27 Oct 2026 13. [Critical Zendesk update: API tokens being replaced with OAuth](https://cxsupport.crayon.com/hc/en-us/articles/37230241929757-Critical-Zendesk-update-API-tokens-being-replaced-with-OAuth) (Crayon). Not yet checked 14. [What is the Zendesk Marketplace?](https://developer.zendesk.com/documentation/marketplace) (Zendesk Developer Docs). Not yet checked Wrong or out of date? POST https://oauth-guide.akshatsethi.com/api/reports with {"app": "zendesk", "step": 2, "message": "what you saw"} (step is optional), or call the report_problem MCP tool. The next research run checks it. Followed it? Say how it went: POST https://oauth-guide.akshatsethi.com/api/reports with {"app": "zendesk", "outcome": "worked" | "waiting" | "stuck", "step": 3, "message": "what happened"}, or call the report_setup MCP tool.