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.
To register your application
- In Zendesk Support, click Manage (
) and then select API in the Channels category.
- Click the OAuth Clients tab on the Channels/API page, and then click the plus icon (+) on the right side of the client list.
- 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.
- 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.
- 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.
- 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 grant types. This article describes the authorization code grant type in detail. Another flow, the implicit grant type, is similar to the first except it doesn't use an authorization code. The third option, the password grant type, is a server-side grant type that doesn't require interacting with end users.
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.
For more on the scope, see OAuth Tokens for Grant Types.
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 specified in an OAuth client in the Support admin interface (Admin > Channels > API > OAuth Clients). See Registering your application with Zendesk.
- client_secret - Use the secret specified in an OAuth client in the Support admin interface (Admin > Channels > API > OAuth Clients). See Registering your application with Zendesk.
- redirect_uri - The same redirect URL as in step 3. For ID purposes only.
- scope - See Setting the scope..
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. No endpoint exists to create the token or set its scope. The token grants read and write access to all resources.
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 agent@zendesk.com.
Example response
Status: 200 OK
{
"access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
"token_type": "bearer",
"scope":"read"
}
62 Comments
Hi James. This article talks about the general OAuth grant flow for getting an authorization token to access the Zendesk Support product. We don't have any specific guidance if moving from the SalesForce solution you mention, however.
If you have specific questions related to OAuth and Zendesk, we can work on answering those. Also, if you want to share your use case, maybe some additional information can help.
Hi Brian,
Thank you for the quick response!
We host files for download on apache server, but require auth for users. We have links in Zendesk pointing to these resources, but again need to be authenticated. So the link in Zendesk could relate to "First Use" in the diagram above, I think. Any pointers will be helpful. Thanks again.
If you're already authenticated into Zendesk Support product's agent interface, clicking on links inside ticket comments that lead to your asset server, that would be one scenario. This article might give a different perspective for that scenario (not necessarily an exact solution for you, but closer to this use case): Using OAuth to authenticate Zendesk API requests in a web app.
If you're accessing these assets via an Apps framework app, that would be a different scenario and would benefit from secure settings.
If these points still don't hit the mark James, I suggest reaching out to support@zendesk.com with more details related to your account and use cases and we can dig into more details there. Hope this is at least a step in the right direction.
Hi, I was hoping to use the client-credentials grant type, but that isn't documented here, is it supported?
https://oauth.net/2/grant-types/client-credentials/
Hi Colin,
The OAuth client credentials grant type isn't supported in Zendesk Support.
Zendesk Chat does support it, however. There are specific setup steps needed. Instructions are here: Implementing an OAuth authorization flow.
Because there is no "non-agent"/system type user, any token created always belongs to a specific agent or admin. This means any actions made with that token will appear to be done by the user who created the token.
Hope this helps!
Is there any way to style the Zendesk Authorization page (where the user chooses to grant or deny access)?
Hi Matt -
The Authorization page is not customizable. Several users have requested this, but the product team determined that it was not something they were going to open up for customization at this time.
Hi there, struggling to wrap my mind around API/OAuth here. We're evaluating a 3rd party tool integration who is requesting API access. With the understanding that this grants them unlimited access to our Zendesk instance, looking for a way to limit this authentication access. It seems like OAuth may be a possibility, but not clear exactly how it works.
Ideally we'd want to provision read-only access to CSAT response data, but permissioning doesn't seem to be that granular. Any thoughts?
Hi Max,
There are a number of ways to authenticate into Zendesk and it's not always clear what they all are and when to use a particular option.
"API Tokens" (Admin > Channels/API > Settings/Token Access) act as a substitute for passwords. If you know the value of an account's API token and know an email in that account, you can combine the two (john@example.com/token:<tokenvalue>) to act under that particular user. Because they are so flexible, they should really only be used in a secure environment such as a backend server or within a script that has limited access.
"OAuth Tokens" are generated under a particular user against an "OAuth Client" (Admin > Channels/API > OAuth Clients). Once generated, these always act under the user they were generated under. They should also be protected to some degree as they act as a "key" for that user to get into Zendesk. If an administrator generates a key for themselves, then that key has administrator rights, and so on with agents and end users (each having the respective rights their profile allows for).
As you noticed, OAuth tokens can have scope as well. Scopes are documented here: https://developer.zendesk.com/rest_api/docs/support/grant_type_tokens#scope. If you want to limit scope and have the access key always be for a particular user, you should use OAuth tokens.
Scope granularity, however, is not that fine. You may have to find a different way to access only CSAT data in a read-only way.
Here are a few good articles that talk about authentication, too:
Having the talk: Am I ready for a more advanced authentication option?
Creating and using OAuth tokens with the API
Authentication for API requests
Generating a new API token
Hope this helps get you to your next step.
Hi Team ,
Any one of you have client code to request to zendesk to create user and tickets ?
Hi Yogesh Dahake -- The REST API community area is more focused on questions around general how-to integration questions -- you may have better luck on users sharing sample code:
https://develop.zendesk.com/hc/en-us/community/topics/360000019807-Zendesk-REST-APIs
I'd also check out these developer resource links on different ways to create integrations with Zendesk:
I went through all the methods mentioned in the Zendesk portal to setup a OAuth Authentication, but in every method either username, password was required or the user is traversed to an Authentication page to authorize, both the things are same but different mode of input.I have a requirement where I have to get an access token or an authorization code with only the following details: client ID, Client Secret, redirect/callback URI. Can anyone please tell me the possibility of getting one?
Thanks in advance for your feedback
Hello Harshith,
Generally speaking, we want the user to provide a form of authentication in order to get an access token.
I feel that it would be useful to know more about your use case, if you can expand on that.
Thank you!
Hi Matteo,
Thanks for your prompt response, actually we had some integration challenges for zendesk in Matillion, for which we have an ongoing discussion(hopefully it will be resolved).In the mean time we were exploring other possible options such as "Client Credentials type" of OAuth authentication, as we have a requirement of having a system account rather than an account tied to an individual.
Kind Regards,
HV
Hi Harshith,
No problems at all.
At the moment, Core API OAuth flows require a user to either authorize via a UI (in the auth code/implicit grant flow) or directly via API in the password grant flow type. I am not aware of any other method you can sue to get around this, so I'm afraid what you're looking for is not possible.
Let me know if there is anything else I can do for you.
Thanks!
Hello,Charles Nadeau ,
I have a question to confirm with you,After I apply for a global client,How to use this global to connect user_domain,
1)What is this process like?
2) How the domain entered by the user is passed to the parameters
Hi lemon -- I replied over in your cross post at https://develop.zendesk.com/hc/en-us/articles/360001074388?page=1#comment_360004834134
Check that out and see if it answers your question. Depending on what you're doing, you may not even need a global OAuth client.
Hi - I've been meaning to implement this in our custom app, but I keep getting this error:
Access to XMLHttpRequest at 'https://<subdomain>.zendesk.com/oauth/tokens' from origin 'http://localhost:8001' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.
I've tried requesting from localhost and 127.0.0.1 and even from our beta website, but to no avail. May I ask what can be done here or is there some auth restriction I haven't read up on yet?
Hi Caye! CORS and localhost don't get along very well, but I found a great article explaining how you can work around this! It isn't written by us, but it explains a number of different methods for resolving this.
Hello Zendesk Commnutity,
I need my application to login to Zendesk to create/update tickets. It's basically a deamon application (no user interaction), will the https://developer.zendesk.com/rest_api/docs/chat/auth#client-credentials-grant-type can be used for Support endpoints? It says grant type is experimental what does mean. Will this be deprecated soon or have limited support available for all Zendesk APIs?
Thanks in an advance
Hello Zendesk,
I found this article very helpful to get the Auth0 token. However, I need to deploy my application on different subdomains and I do not know the name of those subdomains. It triggers a problem to redirect the user in the flow. Is the a way to work around this?
Thanks in advance !
Hi Emile Cohen. The solution would need to request that subdomain info from the user (either through, say, an input field on a form or some sort of preconfigured setting that your app can get to somehow).
Hi Manan! If you are looking for Support functionality, you can not use the Chat OAuth. You will need to use the Support OAuth, which you can find here.
Hey Greg - Community Manager Thanks for response.
What would be best practice for Deamon App login which requires an application to login to perform an action in Zendesk. So do you think using the "password" grant_type is idle for Support API while using Deamon apps?
That really depends on your situation. Password grant types are useful if there is no user interaction required, but you'll want to ensure that your method of sending and storing the credentials are very secure.
Thank Greg - Community Manager for the prompt reply. Security is essential while storing sensitive data.
Just to note, we were able to use the 'client_credentials' grant type for Support API successfully but since not supported and recommended we will go with alternative routes.
We recently created an integration with Zendesk which allows our agents who are logged into the Zendesk support to have access to an internal tool. Every time agents attempt to access our tool, we're presented with a message to "Allow Access to Your Zendesk Account?" This didn't happen during our testing in our Zendesk sandbox account, but it happens in production. Any thoughts on how to make this a one-time "Allow" rather than requiring it every time they log in?
Hi Paul! Could you share a bit more information about this integration and how the auth flow is implemented? Please provide as much detail as you can share in a public forum!
Hi Charles Nadeau
Can you help me out with a similar problem here : https://support.zendesk.com/hc/en-us/community/posts/1260801978190-How-to-perform-Authorization-code-grant-flow-on-Zendesk-with-Agent-when-I-have-SSO-enabled-
Hi Raghav, I responded here!
Please sign in to leave a comment.