DocumentationAPI Reference

Set up a global OAuth client

Set up a global OAuth client

If you distribute a public app or an integration app to multiple Zendesk customers, you must use global OAuth tokens to authenticate requests. You may not use regular API tokens or OAuth tokens because the Zendesk Developer Terms prohibits Zendesk customers from sharing their API credentials with you.

This requirement doesn't apply if you're developing applications or integrations for internal use.

You must request a global OAuth client from Zendesk to create global OAuth tokens. For security reasons, Zendesk doesn't allow developers to create their own global OAuth clients.

Requesting a global OAuth client

To request a global OAuth client

  1. Develop your app using a local OAuth client in your Zendesk account. For more information, see Using OAuth authentication with your application. Note the following requirements when setting up your client:

    • Unique Identifier prefix: Ensure your Unique Identifier is prefixed with the string "zdg-". For example, "zdg-global-unique-identifier".

    • Complete all fields: Make sure all fields are completed for the local client. Even if a field is labeled optional, it is required for global clients.

    • Client name choice: Choose a client identifier that is representative of your product or business. For example, "zdg-zendesk is acceptable" but "zdg-global_client1" is not.

    • Production-ready value: The client identifier should be the exact value intended for production.

    • Separate clients per app: We strongly encourage creating a separate client identifier for each app or integration. Sharing a single OAuth client between different apps is not recommended.

  2. When your app is finished and ready to use across multiple Zendesk accounts, submit your request as described below.

    Note: Make sure you note down the secret and the identifier before making your request. You will lose access to the client administration page after the local client is converted to a global client.

  3. Sign in to the Zendesk Marketplace portal. Select Global OAuth from the menu on the left side, and then click the Request new OAuth button.

  4. Complete the request form. Ensure the subdomain includes the prefix d3v-. Submissions from non-d3v- accounts aren't accepted. Note: The d3v- and the zdg- values are pre-filled in the form. Make sure the values are properly created on the local OAuth client in your sponsored account and that your sponsored account has the proper account prefix as well.

    The form may ask you to specify the scopes your app requires. Provide only the scopes your app genuinely needs. Zendesk uses this information to configure allowed scopes on your global client. See Allowed scopes for global clients.

    To request a sponsored developer account, see Getting a trial or sponsored account for development.

  5. Done! You'll receive an email and a ticket reference with updates on your submission. Please add "[email protected]" to your contact list to ensure you receive e-mail communications from us regarding your submission.

If the request is approved, Zendesk converts your local OAuth client to a global OAuth client.

Allowed scopes for global clients

When Zendesk approves your global OAuth client, Zendesk may configure allowed scopes on the client to restrict it to the scopes your app needs. This applies the principle of least privilege — ensuring your app can only request the access it genuinely requires, rather than broad permissions that could create unnecessary security risk for your customers.

Allowed scopes define the maximum set of scopes your global client is permitted to request during the OAuth authorization flow. For example, if your app only reads ticket data and user profiles, Zendesk may configure your client with tickets:read users:read as its allowed scopes.

How allowed scopes affect your app

When your global client has allowed scopes configured:

  • Your app can only request scopes that are included in the client's allowed scopes during the authorization flow.
  • If your app requests a scope that is not included in the client's allowed scopes, the authorization request fails with a 400 Bad Request response and an invalid_scope error — no token is issued.
  • Customers who install your app will only be asked to grant the specific permissions your client is restricted to, which reduces friction during installation and builds trust.

Best practices

  • During development with your local OAuth client, request only the scopes your app actually uses. This makes the transition to allowed scopes on your global client straightforward and avoids having to renegotiate scopes later.
  • Review which Zendesk API endpoints your app calls and check whether each requires read or write access. Request a scope that covers exactly those resources and access types.
  • If your app's scope requirements change after your global client has been approved, contact Zendesk Support to request an update to the client's allowed scopes. See Why can't I edit my global client?.

For the full list of available scopes and their descriptions, see OAuth scopes.

Frequently asked questions

Why do you need my subdomain even with a global client?

Unlike services like X (formerly Twitter) or Facebook that behave as global authentication systems, Zendesk maintains separate logins for each Zendesk account or subdomain. When a customer signs in, they're signing into a specific Zendesk subdomain which carries over to OAuth. When a Zendesk account owner uses OAuth to authorize your service, they're authorizing the service for their subdomain. So we need to know your subdomain.

Why can't I edit my global client?

Zendesk must take control of the client to make it global. It can only be edited by our Marketplace Operations Team. If you are having trouble with your global client, reach out to Zendesk Support by following the instructions here and using "Option 2". Be sure to mention "global oauth" when you describe your issue to the bot and include the client_id as well as the changes you need made.

What if my app needs different or additional scopes than what Zendesk configured?

Because global clients can only be edited by the Zendesk Marketplace operations team, you'll need to contact Zendesk Support to request a change to your client's allowed scopes. See Contacting Zendesk customer support and use "Option 2". Be sure to mention "global oauth allowed scopes" and include your client_id and the specific scopes you need added or changed.

Can I use my global OAuth client for my bot?

You will need to request a separate OAuth token when creating a bot. You cannot use a Zendesk Support global OAuth for building a bot using Sunshine Conversations.

Does this global OAuth client work with Zendesk Sell?

No, these instructions only apply for Zendesk Support and Chat (Agent Workspace enabled) accounts. For Zendesk Sell, you will need to register a Multi-User Application as part of the authentication flow.

Next steps: Create assets