Zendesk provides 3 ways of authenticating API requests:
- basic authentication with a username and password
- API token
- OAuth access token
You normally opt for OAuth tokens when you need users to grant your application access to their accounts. This involves building an OAuth authorization flow.
You can also use OAuth tokens for other types of requests that don't require user authorization. For example, you might use them in applications used by internal staff or by the general public. Using OAuth tokens for authentication doesn't tie the requests to a specific username and password, and it offers more control and security than plain API tokens.
The following example is a request that uses an OAuth token for authentication:
curl https://obscura.zendesk.com/api/v2/users.json \
-H "Authorization: Bearer 52d7ef4ee01e2c2c75bff572f957cd4f12d6225eee07ea2f01d01a"
Topics covered in this article:
Creating a token with the Zendesk API
The section describes the steps to create an OAuth access token with the Zendesk API:
You can use basic authentication or an API token to make Zendesk API requests. Don't confuse an API token with an OAuth access token. You can get an API token from the Support admin interface. See API token in the Support API docs.
If your organization uses single sign-on (SSO) and the Zendesk passwords were deleted from the Zendesk account, you'll have to use an API token to make the requests.
Create an OAuth client
- In Zendesk Support, select Admin > Channels > API > OAuth Clients.
- Complete the form. See Registering your application with Zendesk for details.
Get the client ID
Use the List Clients endpoint to get the id of your new client.
Request
Basic authentication
curl https://{subdomain}.zendesk.com/api/v2/oauth/clients.json \
-v -u {email_address}:{password}
API token
curl https://{subdomain}.zendesk.com/api/v2/oauth/clients.json \
-v -u {email_address}/token:{api_token}
Response
{"clients":
[
{
"name": "OAuth client for my app",
"id": 50328,
"user_id": 293241756,
...
},
...
]
}
Create the access token
Use the client id in the Create Token endpoint to get an access token.
The endpoint can only be used by Support admins.
Request
Basic authentication
curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json \
-d '{"token": {"client_id": "50328", "scopes": ["read", "write"]}}' \
-H "Content-Type: application/json" \
-X POST -v -u {email_address}:{password}
API token
curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json \
-d '{"token": {"client_id": "50328", "scopes": ["read", "write"]}}' \
-H "Content-Type: application/json" \
-X POST -v -u {email_address}/token:{api_token}
Learn more about scopes in Setting the scope in the Zendesk Support Help Center.
Response
{"token":
{
"full_token":"52d7ef4ee01e2c2c75bff572f957cd4f12d6225eee07ea2f01d01a",
"scopes":["read","write"],
...
}
}
The full_token
property specifies the access token. Keep the value in a safe place.
Use the access token in requests
Use the access token in an Authorization header in your requests. Example:
curl https://{subdomain}.zendesk.com/api/v2/users.json \
-H "Authorization: Bearer 52d7ef4ee01e2c2c75bff572f957cd4f12d6225eee07ea2f01d01a"
In cURL, the -H
flag indicates a header field.
9 Comments
Not sure if it was intended, but there is .example in the following examples.
Not intended. I fixed the URLs. Thanks, Matt.
Hi Charles,
Will the token be expired? From the support document, it said that the token will never expire.
What if I want to have an OAuth Token which is only valid for 2 hours? How should I do?
Thanks.
The statement that "using OAuth tokens for authentication doesn't tie the requests to a specific username and password" is true in the sense that anyone in possession of the OAuth token can use it. However, in a way it is tied to a specific user: the user that created it. For example, if user X creates the token and gives it user Y and user Y uses the token to add a comment to a ticket without setting the author_id of the comment to user Y, then the comment by default will be attributed to user X (the creator of the token). That appears to be the phenomenon encountered by one user as described in his comment: https://support.zendesk.com/hc/en-us/articles/226316187/comments/360001755167
You're correct Charles Larry -- OAuth access tokens/keys are always tied to a particular user. When that key is used, the action is effectively performed under the user who created the key.
That's why, depending on the context, securing keys is important. For example, if the key was created by an admin and gets made public somehow, whoever has it can perform any action that admin can perform. If a key is leaked somehow, it should be revoked immediately.
Is it possible to use this method/non-grant type tokens to grant access for the Chat APIs?
The documentation for the Chat Conversation API references setting the scope (singular) to read, write, and chat.
The Create Token end point has scopes (plural) and errors if you include 'chat'.
Requested scopes are invalid. Invalid scopes: chat
Is there another method to set the scope for non-grant type token or do you have to use one of the grant type token methods?
Hi Scott Franke,
The above article focuses on generating an access token for Zendesk Support.
For Zendesk Chat, you'll want to follow the instructions at: Generating a Zendesk Chat OAuth token
Following those instructions, along with the need for including "chat" in the scope, will return an access token that you can use with the Chat Conversations API.
It can be confusing, but for legacy reasons, generating access tokens for Zendesk Support, Chat, and Sell are different unfortunately (for now). Hope this clarifies things!
We have an ETL script from Zendesk to our own Database; we want to make sure this one continues to work even if the person that generates the token is no longer with the company. We've been using a basic + token authentication method; however, it is tied to a user.
Would you recommend using an OAuth token instead? Would this keep the token alive even if the user/admin that generates it is deactivated?
Thanks
Hi Eddy Castillo. For API access to Zendesk Support, these are the possible ways: How can I authenticate API requests
All the available approaches are tied to a user, however. There is no "machine to machine" type user.
The closest you can get to creating a more permanent, non-user-based access token is to fake it and create a specially identified "agent" for these purposes.
The bottom line is, if a user is disabled, their access is disabled, even if they use an OAuth access token. Hope this at leasts sets expectations!
Please sign in to leave a comment.