How to Replace Zendesk API Tokens with OAuth

Zendesk has begun gradually phasing out legacy API tokens in favor of OAuth 2.0. OAuth provides significantly better security through granular access control, time-limited tokens, and improved traceability. To prevent existing integrations from stopping working, all API tokens must be migrated well before the final deadline.

In this guide, we walk through the basic steps for creating an OAuth client in the Zendesk Admin Center and how to get started with the migration.

1. Why is Zendesk phasing out API tokens?

Static API token authentication often provides broad administrative access and can pose a security risk if the key is compromised. OAuth 2.0 offers:

• Principle of least privilege: Limit access to only the API endpoints the integration actually needs.
• Unique access tokens: Avoids sharing static passwords or global administrator tokens in source code.
• Full control and traceability: Easily revoke individual clients if a key is compromised.

2. Step-by-step: How to create an OAuth client

To replace an API token with OAuth, you must first create an OAuth client in the Zendesk Admin Center:

1. Go to the Admin Center in your Zendesk instance by clicking the product switcher in the upper-left corner: 
   
2. In the left menu, select Apps and integrations > APIs > OAuth clients: 
   

3. Click the Add OAuth client button in the upper-right corner of the page:

   

4. Enter the required information in the form:
   • Client Name: A descriptive name for the integration (for example, "PowerBI Integration").
   • Description: What the integration is used for.
   • Company: The company name users will see when they are asked to authorize the OAuth client.
   • Logo: A logo shown to the user when they are asked to authorize the OAuth client.
   • Identifier: A unique identifier used for client_id. It is not shown to the user.

   • Client type: Clients are divided into public and confidential clients. For clients running on a secure server where a client secret (client_secret) can be stored safely, use a confidential client.

     Where secrets cannot be kept hidden such as in mobile apps or browser-based apps (SPAs), use a public client. For these clients, you must use the OAuth 2.0 Authorization Code Flow with PKCE to prevent unauthorized parties from obtaining and misusing the authorization code.

   • Redirect URL: The URL where the authorization code should be sent (required for the conventional OAuth flow).
   • Allowed scopes: You can select the scopes the client can request, for example, read and write access to the help center only (hc:read, hc:write).
   • Secret: This is generated by Zendesk as soon as you click Save.
5. Click Save. The system will now generate a Secret corresponding to client_secret.
   Important: Remember to copy and store this key in a secure location. It is shown only once, but you can always generate a new secret if needed.

3. Configuring your integrations

Once the OAuth client has been created, the authentication code in your scripts, applications, or third-party systems must be updated to use the OAuth 2.0 authorization flow (for example, Authorization Code Flow or Client Credentials Flow) instead of Basic Auth with an API token.

Read our original update article:
Critical Zendesk update: API tokens are being replaced with OAuth