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 third-party OAuth to a Support app.
- 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 Admin Center, click
Apps and integrations in the sidebar, then select APIs > Zendesk API.
- Click the OAuth Clients tab on the Zendesk API page, and then click Add OAuth client on the right side of the OAuth 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.
- Client kind - Public or Confidential. Public OAuth clients are applications that run in environments where credentials cannot be securely stored, such as mobile and web apps. These clients are required to use PKCE. Confidential OAuth clients run on secure servers where their credentials can be kept secure. These clients can use PKCE, client secret, or both. See OAuth client types.
- 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.
OAuth client types
Zendesk OAuth clients include a kind
property that is passed during
OAuth client creation, and can have one of the following values:
- Public: Public OAuth clients are applications that run in environments where credentials cannot be securely stored, such as mobile and web apps. These clients are required to use PKCE.
- Confidential: Confidential OAuth clients run on secure servers where their credentials can be kept secure. These clients can use PKCE, client secret, or both.
For more information, see Client Types.
Zendesk OAuth client type applies only to the Zendesk Support ticketing system. It is not supported in Chat, Conversations, or Sell.
Existing Zendesk OAuth clients currently have the kind
property set to
unknown
. These clients remain unaffected until the
kind
property is updated to either public
or
confidential
. New OAuth clients created in Admin Center must set the
kind
property during creation.
kind
property to public
, you must first
implement PKCE. Failure to do so will result in the client not working, as PKCE will be
immediately required.Setting the kind
property is mandatory for all new OAuth clients created
in Admin Center. While the kind
property is not required for OAuth
clients created with the api/v2/oauth/clients endpoint
, Zendesk
recommends including it.
Implementing an OAuth authorization flow in your application
Zendesk supports the authorization code grant flow to get access tokens. This flow is called the authorization code grant flow because you have to get an authorization code before you can request an access token. Other grant flows have been deprecated.
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.
The authorization code grant method supports Proof Key for Code Exchange (PKCE), which adds an additional layer of security. For more information, see Using PKCE to make Zendesk OAuth access tokens more secure in the developer documentation.
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 core subdomain, not a host-mapped
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 to 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. - code_challenge - Required if using PKCE. A string representing a code challenge derived from a code verifier. See Generating the code_challenge value in the developer documentation.
- code_challenge_method - Required if using PKCE. The method used to derive the code challenge. Specify "S256" as the value.
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
- webhooks
- zis
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 only valid for 120 seconds.
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.
If you use the PKCE
code_challenge
andcode_verifier
parameters,client_secret
is not required. You can use this characteristic to migrate from the implicit grant flow, which is no longer recommended because of security concerns. See Using PKCE to migrate from the implicit grant flow in the developer documentation. - redirect_uri - The same redirect URL as in step 1. For ID purposes only.
- scope - See Setting the scope.
-
code_verifier - Required if using PKCE. The string used to generate the
code_challenge
value. See Generating the code_challenge value in the developer documentation.
The request must be over https and the properties must be formatted as JSON. If you use a custom or third-party application to make the API request, see its documentation for the proper format of property values.
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"
58 comments
PAUL STRAUSS
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?
0
Greg Katechis
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!
0
Groffer Anderson
Hi @...
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-
0
Greg Katechis
Hi Raghav, I responded here!
0
Nick Hemenway
Hello, I'm trying to implement the Password grant type OAuth flow, and I'm having trouble understanding how I'm supposed to obtain the user's username and password in order to request the OAuth token for the first time. This section seems to imply that there is an endpoint to retrieve the username and password I need, but I haven't been able to find this endpoint. Any advice? Thanks
![](/hc/user_images/LG8yUFzrhd1lVYuX0ABmUw.png)
0
Vitaliy Markitanov
Hello,
Do you support OIDC brokering?
Idea is that I have IDP and my web users should authenticate with my IDP via SSO.
0
Jason Schaeffer
Hello Vitaliy,
Zendesk does not currently support OpenID Connect, and according to our product team, this is not currently something on our Road Map. Apologies for the inconvenience.
0
Paul Moran
The "authenticity_token" mentioned in the comment above https://support.zendesk.com/hc/en-us/articles/203663836/comments/360000042747 doesn't work for me. The format of the csrf_token (which I was able to access using the v1 template api) and this authenticity_token are different.
0
Bernardo Reis
Hi there. I've implemented the OAuth authentication flow as suggested and have requested the following scopes:
Everything works as expected, except when I try to use Zendesk's API to delete user identities. I get the following error:
Shouldn't the 'users:write' scope let me manage user identities? Or do I need an additional scope? Looks like that 'identities:write' is not a valid option
3
Ariane Frances dela Cruz
Hello Bernardo,
I'd like to look further into this, I'll be creating a ticket for you, kindly expect an email shortly.
0
Greg Katechis
Hi Tiel! Is this in relation to a Zendesk feature or is this just a general question about Oauth?
1
Nishant Gupta
I have been trying to implement OAuth in Rest API.
Please note that I don't have web app(in which I can use redirect URL)
Only Backend - REST api
With all the oauth Authentication types, it is confusing to follow which one is the best to do.?
Which curl commands helps me authenticating with Zendesk successfully using oauth
Is the password grant type best suited for this type with below curl command? or what alternatives we have ?
0
Viktor Hristovski
Hi, im generating an OAuth token in Zendesk for our developers, but we are getting :unauthorised" even in the simple curl command for example:
curl https://obscura.zendesk.com/api/v2/users.json \
-H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"
we are getting : {"error":"invalid_token","error_description":"The access token provided is expired, revoked, malformed or invalid for other reasons."}
What are we doing wrong?
0
Chinh Phan
Hi,
How can I get the full access token within just one API? I'm using javascript to call, and implement a ticket form from my website.
1
Cheeny Aban
Hi Chinh Phan
What do you mean by full access API token? Can you tell us more about your use case so we can check it for you?
0
Chinh Phan
Hi Cheeny Aban,
I'm implement the contact form from Frontend via Javascript, submit Ticket to Zendesk. Look like this:
When I try to POST a ticket to zendesk, I'm facing the CORs issue (I used all tokens, aouth in zendesk setting).
Ticket's API requires the authorization is "Bearer " + access_token.
I thought the API get access_token work when I tested via Postman: https://{subdomain}.zendesk.com/api/v2/oauth/tokens
But no, when I apply API get access token to javascript code. I'm also facing the CORs issue.
If I implement as in the document at: https://support.zendesk.com/hc/en-us/articles/203663836?page=3#topic_ar1_mfs_qk
when browser redirect to the url: https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&redirect_uri={your_redirect_url}&client_id={your_unique_identifier}&scope=read%20write
It forces I have to login into zendesk. It is not feasible for users who do not have an account.
1
Óskar Ómarsson
Not sure if this is the correct place to ask this but I'm trying to create a workaround for limitations in Zendesk Automation, I need to be able to add private comments to a ticket when an automation does change the ticket, just to inform any agent that would open up the ticket after the automation is executed.
Now I've achieved this using Webhooks to call Zendesk API
But only by using my own username, this will result in a certain username being placed with the comment, making it look like I made that internal comment.
My desire is to make it look like the system, which indeed is doing this, made the internal comment.
It appears that I can't use the Zendesk API Token unless I use my own username, please correct me if I'm wrong
And I can't get the OAuth Client tokens to work as a bearer token authentication.
What am I missing?
Best regards
Oskar
1
Taylor Clark
Is there an existing query parameter I can use to force login on the authorization step? Currently if a user is already logged in it goes directly to the Authorization screen. I'd like to force users to login every time they go through the flow.
The use case is that our integration requires an administrator and we can't figure this out until after we retrieve the token and then retrieve the authenticated user by ID
0
Taylor Clark
Actually figured it out just now using the UI - `&login=true`
0
Marshal
I have a trial account for zendesk and I am trying to use OAuth for my api requests and it is returning invalid token. If I use basic auth it works but I can't use basic auth for my client side application to make calls because of the CORS policy. I would love to know if it is possible to use OAuth with my trial account?
0
Cheeny Aban
Yes, OAuth token use is supported in Trial accounts. If you are seeing invalid token errors, I would recommend that you double-check our documentation on setting up different OAuth grant flows to ensure that the parameters of your requests are in line with our expected tokens as per that article. If you are still seeing errors, I would recommend that you open a ticket with us, so we can dig deeper and investigate.
0
Jishnu S
Hi Team,
I have followed your instructions and I got the access token. But there is no information about finding the authenticated user-id using the access token.
Can you please advise me to find authenticated user details?
Thanks
0
Greg Katechis
Hi Jishnu! We don't currently provide support for the underlying standard (OpenID Connect), so there is not currently any way to retrieve user data from an access token.
0
Vlad Glazov
Hello
Is there any way to revoke global OAuth client? What if it was created by the member who left organization?
Thanks
0
Jonas Rocha Lima Amaro
Hello
Can an OAuth client have more than one access token, or bearer token as you may?
I ran
request twice in a row and the second one revoked my authorization_code. I suspect that it is caused by some sort of Single Access Token Per Subject policy, right?
Thank you
0
Dane
It can be revoked using the endpoint Revoke Token.
@Jonas,
As it turns out, you are not allowed to use multiple access tokens. Hence, the behavior you have experienced is expected.
0
Vlad Glazov
Hi Dane,
Thanks for you answer, revoking a token seems to be clear.
Now how about revoking (or deleting/disabling/whatever) OAuth client?
Thanks, Vlad.
0
Dane
You can use: Delete Client
0
Cesar Mak
Hi Support,
I tried the `Authorization code grant flow` and it worked well to get access token (for listing tickets), but the flow does not suit my application.
So I was trying with the `Password grant type` flow. My account (xyz@abc.com) is an "user" instead of an "admin". Thr organization has 2FA enabled. On trying the POST Api, I got the error below.
Is 2FA a blocking factor for such scenario?
0
Greg Katechis
Hi Cesar! 2FA and OAuth should not be an issue. Have you confirmed that the issue is not one of the (relevant) errors provided in the response?
0