Using OAuth authentication with your application

You can use OAuth 2 to authenticate all your application's API requests to Zendesk. OAuth provides a secure way for your application to access Zendesk data without having to store and use the passwords of Zendesk users, which is sensitive information.

To use OAuth authentication, you need to register your application with Zendesk. You also need to add some functionality to your application to support the OAuth authorization flow.

Topics covered in this article:

• Registering your application with Zendesk
• Implementing an OAuth authorization flow in your application

Related topics:

• For a tutorial on building a web application that implements an OAuth authorization flow, see Building an OAuth web app.
• To implement an OAuth authorization flow in Zendesk apps, see Adding OAuth to apps.
• If you don't need users to grant your application access to their accounts, you can still use OAuth tokens to authenticate API requests. See Creating and using OAuth tokens with the API.

Registering your application with Zendesk

You must register your application to generate OAuth credentials that your application can use to authenticate API calls to Zendesk.

Note: This section describes how to set up an OAuth client for users of one Zendesk account. If your application will interact not only with one Zendesk account but with lots of them, you can request a global OAuth client. A global OAuth client is a secure, cleaner way of doing API authentication with multiple Zendesk instances. For more information, see Using a global OAuth client to integrate with Zendesk.

To register your application

1. In Zendesk Support, click Manage () and then select API in the Channels category.
2. Click the OAuth Clients tab on the Channels/API page, and then click the plus icon (+) on the right side of the client list.
3. Complete the following fields to create a client:
   • Client Name - Enter a name for your app. This is the name that users will see when asked to grant access to your application, and when they check the list of third-party apps that have access to their Zendesk.
   • Description - Optional. This is a short description of your app that users will see when asked to grant access to it.
   • Company - Optional. This is the company name that users will see when asked to grant access to your application. The information can help them understand who they're granting access to.
   • Logo - Optional. This is the logo that users will see when asked to grant access to your application. The image can be a JPG, GIF, or PNG. For best results, upload a square image. It will be resized for the authorization page.
   • Unique Identifier - The field is auto-populated with a reformatted version of the name you entered for your app. You can change it if you want.
   • Redirect URLs - Enter the URL or URLs that Zendesk should use to send the user's decision to grant access to your application. The URLs must be absolute and not relative, https (unless localhost or 127.0.0.1), and newline-separated.
4. Click Save.

   After the page refreshes, a new pre-populated Secret field appears on the lower side. This is the "client_secret" value specified in the OAuth2 spec.

5. Copy the Secret value to your clipboard and save it somewhere safe. Note: The characters may extend past the width of the text box, so make sure to select everything before copying.
   Important: For security reasons, your secret is displayed fully only once. After clicking Save, you'll only have access to the first nine characters.
6. Click Save.

Use the unique identifier and the secret value in your application as described in this following topic.

Implementing an OAuth authorization flow in your application

Zendesk supports several OAuth flows. This article describes the authorization code grant flow in detail. Another flow, the implicit grant flow, is similar to the first except it doesn't use an authorization code. The third option, the password grant flow, is a server-side grant type that doesn't require interacting with end users.

• Authorization code grant flow
• Implicit grant flow
• Password grant type

Authorization code grant flow

This flow is called the authorization code grant flow because you have to get an authorization code before you can request an access token.

The flow doesn't use refresh tokens. The access token doesn't expire.

To implement the authorization code grant flow, you need to add the following functionality to your application:

• Step 1 - Send the user to the Zendesk authorization page
• Step 2 - Handle the user's authorization decision
• Step 3 - Get an access token from Zendesk
• Step 4 - Use the access token in API calls

For a tutorial on building a web application that implements an OAuth authorization flow, see Building an OAuth web app.

Step 1 - Send the user to the Zendesk authorization page

First, your application has to send the user to the Zendesk authorization page. The page asks the user to authorize your application to access Zendesk on their behalf. After the user makes a choice, Zendesk sends the choice and a few other bits of information back to your application.

To send the user to the Zendesk authorization page

Add a link or button in your application that sends the user to the following URL:

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

where {subdomain} is your Zendesk subdomain. You can use either a POST or a GET request. Include the following parameters:

• response_type - Required. Zendesk returns an authorization code in the response, so specify code as the response type. Example: response_type=code.
• redirect_uri - Required. The URL that Zendesk should use to send the user's decision to grant access to your application. The URL has be absolute and not relative. It also has to be secure (https), unless you're using localhost or 127.0.0.1.
• client_id - Required. The unique identifier you obtained when you registered your application with Zendesk. See the section above.
• scope - Required. A space-separated list of scopes that control access to the Zendesk resources. You can request read, write, or impersonate access to all resources or to specific resources. See Setting the scope.
• state - An arbitrary string included in the response from Zendesk after the user decides whether or not to grant access. You can use the parameter to guard against cross-site request forgery (CSRF) attacks. In a CSRF attack, the end user is tricked into clicking a link that performs an action in a web application where the end user is still authenticated. To guard against this kind of attack, add some value to the state parameter and validate it when it comes back.

Make sure to URL-encode the parameters.

Example GET request

https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&redirect_uri={your_redirect_url}&client_id={your_unique_identifier}&scope=read%20write

The Zendesk authorization page opens in the end user's browser. After the user makes a decision, Zendesk sends the decision to the redirect URL you specified in the request.

Setting the scope

You must specify a scope to control the app's access to Zendesk resources. The read scope gives an app access to GET endpoints. It includes permission to sideload related resources. The write scope gives an app access to POST, PUT, and DELETE endpoints for creating, updating, and deleting resources.

The impersonate scope allows a Zendesk admin to make requests on behalf of end users. See Making API requests on behalf of end users.

For example, the following parameter gives an app read access to all resources:

scope=read

The following parameter gives read and write access to all resources:

scope=read write

You can fine-tune the scope to the following resources:

• tickets
• users
• auditlogs (read only)
• organizations
• hc
• apps
• triggers
• automations
• targets

The syntax is as follows:

scope=resource:scope

For example, the following parameter restricts an app to only reading tickets:

scope=tickets:read

To give an app read and write access to a resource, specify both scopes:

scope=users:read users:write

To give an app write access only to one resource, such as organizations, and read access to everything else:

scope=organizations:write read

Step 2 - Handle the user's authorization decision

Your application has to handle the response from Zendesk telling it what the user decided. The information is contained in URL parameters in the redirect URL.

If the user decided to grant access to the application, the redirect URL contains an authorization code. Example:

{redirect_url}?code=7xqwtlf3rrdj8uyeb1yf

The authorization code is valid only for a short time.

If the user decided not to grant access to the application, the redirect URL contains error and error_description parameters that inform the app that the user denied access:

{redirect_url}?error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+request

Use these values to control the flow of your application. If the URL contains a code parameter, get an access token from Zendesk as described in the following section. This is the token to include in API calls to Zendesk.

Step 3 - Get an access token from Zendesk

If your application received an authorization code from Zendesk in response to the user granting access, your application can exchange it for an access token. To get the access token, make a POST request to the following endpoint:

https://{subdomain}.zendesk.com/oauth/tokens

Include the following required parameters in the request:

• grant_type - Specify authorization_code as the value.
• code - Use the authorization code you received from Zendesk after the user granted access.
• client_id - Use the unique identifier you received when you registered your application with Zendesk.
• client_secret - Use the Secret value you received when you registered your application with Zendesk.
• redirect_uri - The same redirect URL as in step 3. For ID purposes only.
• scope - Specify read as the value.

The request must be over https and the parameters must be formatted as JSON.

Using curl

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "authorization_code", "code": "{your_code}",
    "client_id": "{your_client_id}", "client_secret": "{your_client_secret}", 
    "redirect_uri": "{your_redirect_url}", "scope": "read" }' \
  -X POST

Example response

Status: 200 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "token_type": "bearer",
  "scope":"read"
}

Step 4 - Use the access token in API calls

The app can use the access token to make API calls. Include the token in an HTTP Authorization header with the request, as follows:

Authorization: Bearer {a_valid_access_token}

For example, a curl request to list tickets would look as follows:

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

Implicit grant flow

The implicit grant flow is similar to the authorization code grant flow except there's no step 3. You request a token instead of an authorization code. In other words, you set the value of the response_type parameter to "token" instead of "code". If the end user authorizes access, the token is sent immediately in the redirect URL.

Example request

https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=token&client_id={your_unique_identifier}&scope=read%20write   

Example responses

If the user grants access to the application, the token is included in the redirect URL.

{redirect_url}#access_token=gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo&token_type=bearer

If the user decides not to grant access to the application, the URL contains error and error_description parameters.

{redirect_url}#error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+request

Password grant type

Use the password grant type to exchange a Zendesk username and password for an access token directly. This grant type should only be used if your application can get Zendesk usernames and passwords. This is usually a highly privileged application with Zendesk. The application should never store the usernames and passwords. It should also be highly secure about how it gets them.

Example request

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "password", "client_id": "{your_client_id}", 
    "client_secret": "{your_client_secret}", "scope": "read",
    "username": "{zendesk_username}", "password": "{zendesk_password}"}' \
  -X POST

A Zendesk username is usually an email address such as [e-mail].

Example response

Status: 200 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "token_type": "bearer",
  "scope":"read"
}