OAuth Authentication

OAuth Authentication

You must use OAuth2 to authenticate all your API requests to Zendesk Chat. OAuth provides a secure way for your application to access your account data without requiring sensitive information such as usernames and passwords be sent with the requests.

To use OAuth authentication, you need to register your application with Zendesk Chat by adding an API client. You also need to add some functionality to your application to implement an OAuth authorization flow.

Topics covered:

• Adding an API client
• Implementing an OAuth authorization flow

Adding an API Client

You must add an API client in Zendesk Chat to generate OAuth credentials for your application. Depending on the OAuth flow, the client might not have access to all Zendesk Chat accounts.

This section describes how to add an API client using the Dashboard in Zendesk Chat. You can also add and manage API clients programmatically with the API. See OAuth Clients.

To add a client

1. Sign in as an admin to Zendesk Chat.

2. In the Dashboard, go to Settings > Account, then select the API tab.

3. Click Add API Client.

4. Complete the following fields:

• Client Name - The name of your client. This name will be visible to users when they are prompted to grant access to your application.
• Company - 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.
• Redirect URLs - Enter the URL or URLs that Zendesk Chat should use to redirect users after they decide whether to authorize your application to access Zendesk Chat. The URL must be absolute, not relative, and should use HTTPS unless you are using localhost.

1. Click Create API Client.

   Upon successful creation, a dialog will appear displaying the client id and client secret. Take note of these values as you'll need both to create an OAuth access token later.

2. Save the client secret somewhere safe.

   For security reasons, the entire string is displayed only once. After closing the dialog, you'll only be able to view the first few characters.

Use the client id (also known as the unique identifier) and the client secret in your application as described in this following section.

Implementing an OAuth Authorization Flow

Zendesk Chat supports several OAuth flows. The first flow, the authorization code grant flow, produces an authorization code after the user grants your app access to their account. Your app can then exchange the authorization code for an access token to use in API requests.

The implicit grant flow is similar to the authorization code grant flow, except your app doesn't need to get and exchange an authorization code for an access token. If the user grants access, the token is returned immediately.

On the other hand, the confidential grant type is a grant type that doesn't require end user interactions.

Refresh tokens are only issued for the authorization code grant flow.

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.

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 Chat authorization page
• Step 2 - Handle the user's authorization decision
• Step 3 - Get an access token from Zendesk Chat
• Step 4 - Use the access token in API calls

Step 1 - Send the user to the Zendesk Chat authorization page

First, your application must send the user to the Zendesk Chat authorization page. The page asks the user to authorize your application to access Zendesk Chat as if it was them. After the user makes a choice, Zendesk Chat sends the choice and a few other bits of information back to your application.

To send the user to the Zendesk Chat authorization page

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

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new

The request should be GET, with the following parameters (make sure to URL-encode the parameters):

• response_type - Required. Zendesk Chat 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 Chat should use to redirect users after they decide whether to authorize your application to access Zendesk Chat. The URL must be absolute, not relative, and should use HTTPS unless you are using localhost. This URL should be one of the URLs you provided during client registration.

• client_id - Required. The unique identifier you obtained when you registered your application with Zendesk Chat. See the section above.

• scope - Required. A space-separated list of scopes that control access to the OAuth endpoints. The following scopes are supported: read, write, and chat. Example: scope=read%20write.

  • The read scope gives access to APIs for showing and indexing
  • The write scope gives access to APIs for creating, updating, and deleting
  • The chat scope gives access to the Chat Conversations API

• state - An arbitrary string included in the response from Zendesk Chat after the user decides whether 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.

• subdomain - Zendesk Support subdomain. Required if your users access Chat from a Zendesk Support subdomain (such as .zendesk.com/chat). This value is used to sign in the users.

Step 2 - Handle the user's authorization decision

Your application must handle the response from Zendesk Chat indicating the user's decision.

When the user authorizes the application, the authorization code will be found in the redirected URL parameters, for example:

{redirect_uri}?code=7xqwtlf3rrdj8uyeb1yf

The authorization code is valid only for a short time.

If the user decides to deny the application, the URL will contain an error parameter.

{redirect_uri}?error=access_denied

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

Step 3 - Get an access token from Zendesk Chat

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

https://{subdomain}.zendesk.com/oauth2/chat/token

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 Chat after the user granted access.
• client_id - Use the unique identifier you received when you registered your application with Zendesk Chat.
• client_secret - Use the secret value you received when you registered your application with Zendesk Chat.
• redirect_uri - The URL of the resource that Zendesk Chat should send the access token. It again should be one of the URLs you specified during client registration.
• scope - Specify read as the value.

The request must be over HTTPS and the parameters must be URL-encoded.

Using curl

curl https://{subdomain}.zendesk.com/oauth2/chat/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=authorization_code&code={your_code}&client_id={your_client_id}
     &client_secret={your_client_secret}&redirect_uri={your_redirect_uri}&scope=read%20write' \
  -X POST

Example response

HTTP/1.1 200 OK
Content-Type: application/json

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

Step 4 - Use the access token in API calls

The access token is required to make API calls. Set the token in the request's authorization header as follows:

Authorization: Bearer {a_valid_access_token}

For example, a curl request to show your account details would look as follows:

curl https://{subdomain}.zendesk.com/api/v2/chat/account \
  -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. Additionally, you will request an access 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. The implicit grant flow is meant for browser-based JavaScript apps with no server-side component. Because all the app's source code is loaded in the browser, the client secret can't be kept confidential and isn't used.

Example request

To send the user to the Zendesk Chat authorization page, follow step 1 of Authorization code grant flow, with a small change to response_type parameter. Zendesk Chat returns a token directly in the response, so specify "token" as the response type

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=token&client_id={your_unique_identifier}&scope=read&redirect_uri=http%3A%2F%2Flocalhost%2Ftoken

Example response

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

{redirect_url}#access_token=gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo&token_type=Bearer&scope=read

If the request is malformed, invalid or 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

Confidential Grant Type

The Chat API supports the confidential grant type using client credentials.

This grant type is recommended primarily for applications that need to access their own resources. It allows you to exchange the id and secret of an OAuth client for an access token. When making an HTTP request for an access token, an Authorization header is not required. Instead, the authentication and authorization credentials should be included in the body of the request as values of the client_id and client_secret keys. Actions performed using the access token obtained from this grant type are executed and logged as the administrator who created the OAuth client.

This grant type can only be used with a Chat OAuth client that has its client_type property set to "confidential". With this setting, you allow the use of the confidential grant type without any additional side effects. The client can still be utilized with other authorization flows. To set the client_type to "confidential," you must use the Update Client API endpoint.

There are no options to change the client_type setting through the UI. If you re-save the OAuth client via the UI, this setting will revert to "public".

It’s important to use the confidential grant type only if your web application is highly secure and can securely manage the necessary credentials without exposing them on the client side or compromising them in any way. This grant type is not suitable for mobile applications or client-side browser apps.

For more details on the concepts of confidential and public OAuth clients, see the OAuth 2.0 Authorization Framework RFC 6749.

Using curl

curl https://{subdomain}.zendesk.com/oauth2/chat/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=client_credentials&client_id={your_client_id}&client_secret={your_client_secret}' \
  -X POST

Example response

HTTP/1.1 200 OK
Content-Type: application/json

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