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 Chat-only 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
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

Sign in as an admin to Zendesk Chat.
In the Dashboard, go to Settings > Account, then select the API tab.
Click Add API Client.
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.

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.
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.

The other options are the following confidential grant types that don't require interacting with end users:

Password grant type
Client credentials type

Refresh tokens are only issued for the authorization code grant and password grant flows.

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 OKContent-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, 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

Confidential grant types

The Chat API supports the following confidential grant types:

Password grant type
Client credentials type

You can only use these grant types with a Chat OAuth client that has its client_type property set to "confidential". The "client_type": "confidential" setting enables support for the confidential grant types. The setting has no other side effects. For example, you can still use the client with other authorization flows.

You can only set client_type to "confidential" with the Update Client endpoint in this API. There's no UI option for changing the setting. If you resave the OAuth client using the UI, the setting reverts to "public".

Only use a confidential grant type if your web application is highly secure and can get the needed credentials securely without exposing them client-side or compromising them in any other way. Confidential grant types should not be used in mobile apps or client-side browser apps.

An HTTP request for an access token doesn't require an Authorization header. The authentication and authorization credentials are passed in the body of the request -- username and password for password grants, or client_id and client_secret for client credentials grants.

See OAuth 2.0 Authorization Framework RFC 6749 for details on the concepts of confidential and public OAuth clients.

Password grant type

Use the password grant type to exchange a Zendesk Chat username and password for an access token.

This grant type is only supported on Chat-only accounts. It's not supported on Chat+Support accounts. See About Chat account types in Zendesk help.

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 OKContent-Type: application/json
{  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",  "refresh_token": "x4AoIVTmaoZmpl25ZX6vTPL2f0aZXHbn",  "token_type": "bearer",  "scope":"read"}

Client credentials grant type

This grant type is only recommended for applications to access their own resources. You can use it to exchange the id and secret of an OAuth client for an access token.

Actions performed with the access token from this grant type are performed and logged as the administrator who created the OAuth client.

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 OKContent-Type: application/json
{  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",  "token_type": "bearer",  "scope":"read"}