OAuth Authentication

You can 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 that sensitive information like usernames and passwords be sent with the requests.

If you created your Zendesk Chat account in Zendesk Support, you must authenticate your API requests with an OAuth access token.

If you have a stand-alone Chat account that wasn't created in Zendesk Support, you can use OAuth authentication but it's not required. See Security and Authentication in the introduction.

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

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 is the name that users will see when asked 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 or not to authorize your application to access Zendesk Chat. The URLs must be absolute and not relative, https or localhost.
  5. Click Create API Client.

    If the client is successfully created, a dialog appears listing a client ID and a client secret. You'll need both to create an OAuth access token later.

  6. 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 cliend 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, uses an authorization code after getting user confirmation to exchange for an access token that acts on behalf of that user. The other two options are server-side grant types that don't require interacting with end users.

  • Authorization code grant flow
  • Implicit grant flow
  • Password grant type
  • Client credentials 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.

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 has to 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://www.zopim.com/oauth2/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 or not to authorize your application to access Zendesk Chat. The URL has be absolute and not relative. It also has to be secure (https), unless you're using localhost. This URI should be one the URI 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 decide 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.

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

Step 2 - Handle the user's authorization decision

Your application has to handle the response from Zendesk Chat telling it what the user decided. The information is contained in URL parameters in the redirect URL you specified when you registered your application.

If the user decided to authorize the application, the 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 authorize the application, the URL contains error parameter that inform you that the user denied access to your application.

{redirect_url}?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://www.zopim.com/oauth2/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 URIs 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://www.zopim.com/oauth2/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://www.zopim.com/api/v2/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. 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. The implicit grant flow is meant for browser-based JavaScript apps with no server-side component. Since all of 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, please 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://www.zopim.com/oauth2/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
Password grant type

Use the password grant type to exchange a Zendesk Chat username and password for an access token directly. This grant type should only be used if your application is highly secured, client_type is "confidential", and it can get Zendesk Chat usernames and passwords.

Note: You can only set client_type as "confidential" with the Update Client endpoint. There's no UI option to change the setting. If you resave the client using the UI, the setting reverts to "public".

This is usually a highly privileged application with Zendesk Chat. The application should never store the usernames and passwords. It should also be highly secure about how it gets them. Zendesk Chat also limits the usage of this grant type to username/password of users under the same account with the client owner that requests this grant type.

Using cURL

curl https://www.zopim.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=password&username={zendesk_chat_username}&password={zendesk_chat_password}&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",
  "refresh_token": "x4AoIVTmaoZmpl25ZX6vTPL2f0aZXHbn",
  "token_type": "bearer",
  "scope":"read"
}
Client credentials grant type

This grant type is experimental for now. The client credentials grant flow is used to access API endpoints designed specifically for applications rather than for users. An example might be an endpoint that lets an application get statistics about its users. Therefore, this grant type only has limited access to the owner of the client. The client_type must be "confidential" and there is no refresh token issued for this grant. Zendesk Chat currently doesn't have any application-only endpoints.

Note: You can only set client_type as "confidential" with the Update Client endpoint. There's no UI option to change the setting. If you resave the client using the UI, the setting reverts to "public".

Using cURL

curl https://www.zopim.com/oauth2/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"
}