{"slug":"zendesk","name":"Zendesk","domain":"zendesk.com","category":"Customer support","summary":"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.","tier":"reviewed","tierReason":"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.","quality":"researched","updatedAt":"2026-10-27","composio":{"status":"managed","note":"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.","toolkit":"ZENDESK"},"totals":{"effort":{"min":4,"max":10,"unit":"hours"},"wait":null,"firstConnection":"Today, in about 30 minutes, on your own Zendesk subdomain using a local OAuth client"},"stages":[{"id":"build","name":"Your instance","whoCanConnect":"Only users on the single Zendesk subdomain where you created the local OAuth client","userSees":"The Zendesk authorization page on your subdomain, showing your client name, logo and requested scopes","effort":{"min":20,"max":45,"unit":"minutes"},"wait":{"min":0,"max":0,"unit":"minutes"},"unlock":"Zendesk approves your global OAuth request and accepts your Marketplace integration submission","evidence":{"kind":"docs","sources":["s4","s5"],"confidence":"high"}},{"id":"launch","name":"Any Zendesk customer","whoCanConnect":"Admins and users on any Zendesk subdomain","userSees":"The Zendesk authorization page on their own subdomain, listing only the scopes Zendesk allowed for your global client","effort":{"min":4,"max":10,"unit":"hours"},"wait":null,"unlock":null,"evidence":{"kind":"docs","sources":["s1","s7","s9","s11"],"confidence":"high"}}],"requirements":[{"id":"zendesk-admin-account","label":"Zendesk account with admin access","detail":"You need admin rights in Admin Center to create OAuth clients. A free 14-day Support trial works for building.","stage":"build","actor":"you","evidence":{"kind":"docs","sources":["s4","s3"],"confidence":"high"}},{"id":"sponsored-d3v-account","label":"Sponsored developer account with a d3v- subdomain","detail":"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.","stage":"launch","actor":"you","evidence":{"kind":"docs","sources":["s1","s3"],"confidence":"high"}},{"id":"marketplace-org","label":"Organization registered on the Marketplace portal","detail":"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.","stage":"launch","actor":"you","evidence":{"kind":"docs","sources":["s9","s10","s11"],"confidence":"high"}},{"id":"privacy-notice","label":"Privacy notice","detail":"Under the Zendesk Developer Terms, you must publish a privacy notice that discloses what data your integration accesses, uses and stores, and why.","stage":"launch","actor":"you","evidence":{"kind":"docs","sources":["s14"],"confidence":"medium"}},{"id":"https-redirect","label":"HTTPS redirect URI","detail":"Redirect URLs must be absolute and use HTTPS. The only exceptions are localhost and 127.0.0.1.","stage":"build","actor":"agent","evidence":{"kind":"docs","sources":["s5"],"confidence":"high"}}],"steps":[{"id":"create-local-client","title":"Create a local OAuth client in Admin Center","actor":"agent","stage":"build","time":{"min":10,"max":20,"unit":"minutes"},"detail":"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.","actions":["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"],"agentNote":"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.","gotcha":"A local client works only on the subdomain where you created it. Every authorization and token URL includes the user's subdomain.","link":{"label":"Zendesk Admin Center OAuth clients (help article)","url":"https://support.zendesk.com/hc/en-us/articles/4408845965210-Using-OAuth-authentication-with-your-application"},"evidence":{"kind":"docs","sources":["s5","s1","s6"],"confidence":"high"}},{"id":"copy-secret","title":"Copy the client secret and store it securely","actor":"you","stage":"build","time":{"min":2,"max":5,"unit":"minutes"},"detail":"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.","actions":["Copy the secret into your secret manager","Click Save again to finish"],"agentNote":"A person must handle the secret.","gotcha":"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.","evidence":{"kind":"docs","sources":["s5","s1","s10"],"confidence":"high"}},{"id":"configure-client","title":"Configure your OAuth client and test a connection","actor":"agent","stage":"build","time":{"min":10,"max":20,"unit":"minutes"},"detail":"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.","actions":["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"],"agentNote":"An agent can enter the endpoints, client_id and redirect URI and run the test. A person enters the secret.","gotcha":"Refreshing invalidates the previous access and refresh tokens. Store the new pair every time, or users will have to authorize again.","evidence":{"kind":"docs","sources":["s5","s8"],"confidence":"high"}},{"id":"get-sponsored-account","title":"Get a sponsored d3v- developer account","actor":"you","stage":"launch","time":{"min":15,"max":30,"unit":"minutes"},"detail":"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.","actions":["Sign up at zendesk.com/register/free-trial","Rename the subdomain with the d3v- prefix","Submit the form at https://forms.gle/NDkrqK9xkZrnWoyk9"],"agentNote":"A person must sign up and submit the form.","gotcha":"Zendesk suspends sponsored accounts that are used for real customer support.","link":{"label":"Getting a trial or sponsored account","url":"https://developer.zendesk.com/documentation/developer-tools/getting-started/getting-a-trial-or-sponsored-account-for-development/"},"evidence":{"kind":"docs","sources":["s3"],"confidence":"high"}},{"id":"wait-sponsored","title":"Wait for sponsored account conversion","actor":"provider","stage":"launch","time":null,"detail":"Zendesk converts the trial to a sponsored account and notifies you. The docs don't give a timeline.","gotcha":"A trial expires after 14 days, so submit the form early.","evidence":{"kind":"docs","sources":["s3"],"confidence":"medium"}},{"id":"register-org","title":"Register your organization on the Marketplace portal","actor":"you","stage":"launch","time":{"min":15,"max":30,"unit":"minutes"},"detail":"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.","actions":["Sign in at apps.zendesk.com","Register the organization and accept the developer terms","Note the organization ID"],"agentNote":"A person must accept the terms. An agent can then read off the organization ID.","link":{"label":"Zendesk Marketplace portal","url":"https://apps.zendesk.com"},"evidence":{"kind":"docs","sources":["s9","s11"],"confidence":"high"}},{"id":"request-global-client","title":"Request a global OAuth client","actor":"you","stage":"launch","time":{"min":15,"max":30,"unit":"minutes"},"detail":"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.","actions":["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"],"agentNote":"An agent can fill the form. A person should review the scopes and submit.","gotcha":"Zendesk rejects requests from subdomains without the d3v- prefix, and requests where the local client's optional fields are blank.","link":{"label":"Set up a global OAuth client","url":"https://developer.zendesk.com/documentation/marketplace/building-a-marketplace-app/set-up-a-global-oauth-client/"},"image":{"url":"https://zen-marketing-documentation.s3.amazonaws.com/docs/en/request_new_outh_form.png","alt":"Global OAuth request form in the Zendesk Marketplace portal","source":"s1"},"evidence":{"kind":"docs","sources":["s1","s6"],"confidence":"high"}},{"id":"wait-global-approval","title":"Wait for global OAuth approval","actor":"provider","stage":"launch","time":null,"detail":"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.","gotcha":"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.","evidence":{"kind":"docs","sources":["s1"],"confidence":"high"}},{"id":"claim-global-client","title":"Claim the global client in the portal","actor":"you","stage":"launch","time":{"min":5,"max":10,"unit":"minutes"},"detail":"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.","actions":["Click Claim Global Auth","Enter the OAuth identifier and the first 6 characters of the secret","Click Claim"],"agentNote":"Part of the secret is involved, so a person should do this.","link":{"label":"Managing global OAuth clients","url":"https://developer.zendesk.com/documentation/apps/app-developer-guide/managing-global-oauth-clients-and-app-associations/"},"image":{"url":"https://zen-marketing-documentation.s3.amazonaws.com/docs/en/claim_new_global_oauth_client.png","alt":"Claim a global OAuth client dialog","source":"s10"},"evidence":{"kind":"docs","sources":["s10"],"confidence":"high"}},{"id":"submit-integration-app","title":"Submit your integration app to the Marketplace","actor":"you","stage":"launch","time":{"min":2,"max":6,"unit":"hours"},"detail":"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.","actions":["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"],"agentNote":"An agent can prepare the assets and fill in the fields. A person must submit.","gotcha":"Integrations that aren't publicly listed must also create a Marketplace profile and submit.","link":{"label":"Submit your app","url":"https://developer.zendesk.com/documentation/marketplace/publishing-to-the-marketplace/submit-your-app/"},"image":{"url":"https://zen-marketing-documentation.s3.amazonaws.com/docs/en/app-submission-compliance.png","alt":"App submission compliance questions including global OAuth client selection","source":"s10"},"evidence":{"kind":"docs","sources":["s9","s10","s7"],"confidence":"high"}},{"id":"add-headers","title":"Add the Marketplace headers to API calls","actor":"agent","stage":"launch","time":{"min":30,"max":60,"unit":"minutes"},"detail":"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.","actions":["Add the three headers to your API request code","Make calls against the designated test account so Zendesk can see the headers"],"agentNote":"An agent can update the request configuration and run test calls.","gotcha":"Zendesk won't approve the app until it sees these headers on your test account.","link":{"label":"Request header requirements","url":"https://developer.zendesk.com/documentation/marketplace/building-a-marketplace-app/request-header-requirements-for-marketplace-apps"},"evidence":{"kind":"docs","sources":["s11","s9"],"confidence":"high"}},{"id":"wait-marketplace-review","title":"Wait for Marketplace review","actor":"provider","stage":"launch","time":{"min":1,"max":3,"unit":"weeks"},"detail":"Zendesk says new submissions take 1 to 3 weeks and updates take 1 to 2 weeks.","evidence":{"kind":"docs","sources":["s9"],"confidence":"high"}}],"scopes":{"intro":"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.","tiers":[{"scope":"read / write","grants":"Read or write access to all resources","level":"basic","consequence":"Zendesk reviews these as part of the global OAuth request, which asks for the minimum scopes your app needs"},{"scope":"resource:read / resource:write (for example tickets:read)","grants":"Access to a single resource type","level":"basic","consequence":"Nothing extra. These are preferred for a narrow request"},{"scope":"impersonate","grants":"Lets admins act on behalf of end users","level":"sensitive","consequence":"No separate process is documented. It's listed in the global request like any other scope (inferred)"}]},"blockers":[{"symptom":"Global OAuth request is rejected or not accepted","cause":"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","evidence":{"kind":"docs","sources":["s1","s6"],"confidence":"high"}},{"symptom":"OAuth fails for customers on other subdomains","cause":"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","evidence":{"kind":"docs","sources":["s4","s7"],"confidence":"high"}},{"symptom":"400 Bad Request with invalid_scope","cause":"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","evidence":{"kind":"docs","sources":["s1"],"confidence":"high"}},{"symptom":"401 invalid_token after about 30 minutes","cause":"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","evidence":{"kind":"docs","sources":["s8","s5"],"confidence":"high"}},{"symptom":"Marketplace submission stalls","cause":"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","evidence":{"kind":"docs","sources":["s11"],"confidence":"high"}}],"unknowns":[{"question":"How long does global OAuth client approval take?","why":"Zendesk's docs and third-party guides give no timeframe, and no community reports turned up","resolve":"Watch the ticket Zendesk sends after you submit, or ask in Zendesk's developer community"},{"question":"How long does sponsored account conversion take?","why":"The docs only say Zendesk will notify you","resolve":"Submit the form early, while your trial still has time left"},{"question":"Must the global OAuth request be approved before you submit the Marketplace app, or can they run in parallel?","why":"The docs describe both steps but don't say which order is required","resolve":"Ask Marketplace Operations in the global OAuth ticket"},{"question":"What exactly is required for an unlisted (private distribution) integration?","why":"The developer update says unlisted integrations must submit, but no page details how unlisted listings work","resolve":"Check the Marketplace portal submission options or ask Zendesk partner support"}],"handoff":{"agentCan":["Fill in the local OAuth client form in Admin Center once an admin is signed in","Configure your OAuth client with the subdomain-based endpoints, client_id, redirect URI and PKCE","Test a connection against your own instance","Fill in the global OAuth request and app submission forms for review","Add the X-Zendesk-Marketplace-* headers to API calls and run test calls"],"youMust":["Sign up for Zendesk and request the sponsored d3v- account","Copy and store the client secret, and claim the global client with part of it","Register your organization and accept the developer terms","Publish a privacy notice","Submit the global OAuth request and the Marketplace app, and answer Zendesk's tickets"]},"sources":[{"id":"s1","title":"Set up a global OAuth client","url":"https://developer.zendesk.com/documentation/marketplace/building-a-marketplace-app/set-up-a-global-oauth-client/","publisher":"Zendesk Developer Docs","kind":"official","checkedAt":"2026-10-27"},{"id":"s2","title":"Composio managed auth toolkits","url":"https://docs.composio.dev/toolkits/managed-auth.md","publisher":"Composio docs","kind":"composio","checkedAt":"2026-10-27"},{"id":"s3","title":"Getting a trial or sponsored account for development","url":"https://developer.zendesk.com/documentation/developer-tools/getting-started/getting-a-trial-or-sponsored-account-for-development/","publisher":"Zendesk Developer Docs","kind":"official","checkedAt":"2026-10-27"},{"id":"s4","title":"Creating and using OAuth tokens with the API","url":"https://developer.zendesk.com/documentation/ticketing/working-with-oauth/creating-and-using-oauth-tokens-with-the-api/","publisher":"Zendesk Developer Docs","kind":"official","checkedAt":"2026-10-27"},{"id":"s5","title":"Using OAuth authentication with your application","url":"https://support.zendesk.com/hc/en-us/articles/4408845965210-Using-OAuth-authentication-with-your-application","publisher":"Zendesk Help Center","kind":"official","checkedAt":"2026-10-27"},{"id":"s6","title":"How to register your own Zendesk API OAuth app","url":"https://www.nango.dev/docs/api-integrations/zendesk/how-to-register-your-own-zendesk-api-oauth-app","publisher":"Nango docs","kind":"community","checkedAt":"2026-10-27"},{"id":"s7","title":"Developer update: Enhanced security guidelines for third-party apps, integrations, and bots","url":"https://support.zendesk.com/hc/en-us/articles/9590471542170-Developer-update-Enhanced-security-guidelines-for-third-party-apps-integrations-and-bots","publisher":"Zendesk Help Center","kind":"official","checkedAt":"2026-10-27"},{"id":"s8","title":"Announcing the required expiration of global OAuth access and refresh tokens","url":"https://support.zendesk.com/hc/en-us/articles/10212201463962-Announcing-the-required-expiration-of-global-OAuth-access-and-refresh-tokens","publisher":"Zendesk Help Center","kind":"official","checkedAt":"2026-10-27"},{"id":"s9","title":"Submit your app","url":"https://developer.zendesk.com/documentation/marketplace/publishing-to-the-marketplace/submit-your-app/","publisher":"Zendesk Developer Docs","kind":"official","checkedAt":"2026-10-27"},{"id":"s10","title":"Managing global OAuth clients and app associations","url":"https://developer.zendesk.com/documentation/apps/app-developer-guide/managing-global-oauth-clients-and-app-associations/","publisher":"Zendesk Developer Docs","kind":"official","checkedAt":"2026-10-27"},{"id":"s11","title":"Request header requirements for Marketplace apps","url":"https://developer.zendesk.com/documentation/marketplace/building-a-marketplace-app/request-header-requirements-for-marketplace-apps","publisher":"Zendesk Developer Docs","kind":"official","checkedAt":"2026-10-27"},{"id":"s12","title":"Announcing enhanced security guidelines for third-party apps, integrations, and bots","url":"https://support.zendesk.com/hc/en-us/articles/9561388533018-Announcing-enhanced-security-guidelines-for-third-party-apps-integrations-and-bots","publisher":"Zendesk Help Center","kind":"search","checkedAt":"2026-10-27"},{"id":"s13","title":"Critical Zendesk update: API tokens being replaced with OAuth","url":"https://cxsupport.crayon.com/hc/en-us/articles/37230241929757-Critical-Zendesk-update-API-tokens-being-replaced-with-OAuth","publisher":"Crayon","kind":"search","checkedAt":null},{"id":"s14","title":"What is the Zendesk Marketplace?","url":"https://developer.zendesk.com/documentation/marketplace","publisher":"Zendesk Developer Docs","kind":"search","checkedAt":null}],"feedback":{}}