If you're testing or building an internal application, you might not want your API requests to be associated with a specific user, as is the case with basic authentication, which requires a username and password, or with API token authentication, which still requires a username. The third option is using an OAuth access token.
At first glance, creating an OAuth token, with its elaborate authorization flow, might seem like a daunting task. However, you can skip the most complicated parts of the process and get an access token directly from the API. This article describes how to create your very own OAuth token for testing purposes in just a few simple steps.
Creating the OAuth client
Your first step is to create an OAuth client for testing. Navigate to Admin > API > OAuth Clients then click the plus (+) icon on the upper right-hand side of the list. Setting up the client for testing purposes is a little different than creating a normal OAuth client. Note the following differences:
- Your redirect needs to be a valid HTTPS URL, but it doesn't have to be a real website for this project. Example: https://somesite.com.
- Unique identifier is the name of your client for use in code. You can also get the client ID with the List Clients endpoint of the OAuth Client API.
- You may want to copy your secret for future reference. It won't be displayed again after you create it, but you'll want this if you intend to use it to build an OAuth web app or for other projects.
- All other fields can be filled out with dummy data.
Creating the access token
Now you have everything you need to create a token with the OAuth Tokens API . Here's how to make the request with cURL:
curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json \
-H "Content-Type: application/json" \
-d '{"token": {"client_id": "your_client_id", "scopes": ["read", "write"]}}' \
-X POST -v -u {email_address}:{password}
A few things to note about this code:
- Remember to replace the subdomain placeholder with your own subdomain
- The value of "client_id" is the number you copied from the OAuth Clients page
- Set your scopes to ["read", "write"] unless you're specifically testing read-only access to a resource
- 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 authenticate the request:
-u {email_address}/token:{api_token}
. See API token in the Support API docs.
Run your cURL request. It should return a JSON package consisting of a token object with several properties:
The value of "full_token" is your access token. Copy it and keep it safe!
Note that the response's "expires_at" property is "null", which means the token won't stop working until you delete the client itself. Also, next time you visit Admin > API > OAuth Clients , your number of active tokens for your new client should have increased by 1.
Using your new access token
What good is an access token if you don't have anything to use it with? None of the examples below uses a username or password. That's by design! An OAuth access token doesn't depend on any user account, which is one of the advantages of using one in your apps and scripts.
Using an access token to authenticate an API request
Any API call that requires authentication can be made with an OAuth access token. For example, a call to the tickets endpoint that would normally look like this:
curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
-u {email_address}:{password}
looks like this with an access token:
curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
-H "Authorization: Bearer {access_token}"
Using an access token in an API client
You can also use an OAuth access token in any of our API clients . The Ruby client , for example, normally requires authentication with a username and password (or API token), as such:
config.username = "user email" config.password = "user password"
Here's how it looks if you use an access token instead:
config.access_token = "your OAuth access token"
13 Comments
Is there a way to create token using this endpoint for a non-admin user?
@vitaliy - The token creation endpoint is only available to admins. If you have questions on the authentication flow for an app or service you're working on feel free to open up a ticket and we'll assist. Cheers!
The most well written and simple to follow Zendesk article I have read. Great work!
Thanks, Chris! I'm glad you found it useful. :)
The user interface has changed for creating an OAuth token, there's no link anymore to get the client ID via the link. Also, the List Clients endpoint of the OAuth Client API doesn't list our newly created OAuth client.
What are the new steps for finding out OAuth client ID so that we could create a new token for it with desired scope?
Hi Karl -- looks like you're talking about wanting to grab the OAuth Client's internal ID value from the UI -- agreed, it doesn't look like that ID value can be picked up in the UI -- sorry about that.
However, the List Clients API call should be listing out all your OAuth Clients listed under Admin > Channels/API > OAuth Clients, along with their corresponding IDs (and just to be complete, creating a new token via the API is documented here - note that client_id is the numeric id of the OAuth client, not the client's identifier).
If you're not seeing all your OAuth clients via the List Clients API, please do a hard refresh and make sure you're getting the latest. If you're still not getting all your OAuth clients listed, probably best to open a ticket via support@zendesk.com, so it can be investigated further.
Please share any additional info or resolutions here. Thanks!
@Karl you can still get the client id if you know how to open up the network tab in Chrome and inspect the network call to clients endpoint and inspect the JSON response.
@Bryan, does this article still work if you are using Single Sign On? I don't know what I can use for the password argument.
Hi Chris. Unless you've disabled passwords (admin/settings > security > admins & agents tab / Passwords Disabled is checked), you should still have a username/password associated with your account and can use that.
If not, then you could enable it for this exercise.
Or you could generate an OAuth token using a grant flow (see Using OAuth authentication with your appplication). Then you could use the OAuth token in an Authorization header instead of specifying a username/password combination -- example: curl -v -H "Content-Type: application/json" -H "Authorization: Bearer 5888a...." ...
An easy way to generate an OAuth token is to:
1. Go to https://developer.zendesk.com/requests/new
2. Click 'OAuth Implicit Grant', enter your Zendesk subdomain, and click 'Authorize'
The value that appears to the right of the 'Authorize' button is an OAuth token. You can copy that full string and use it in your cURL call as shown above. But be careful, that token is essentially a key into your Zendesk account. You'll want to protect it similar to a password.
Hope this helps!
Please edit this article to put Bryan's "An easy way..." at the very top. This is the only way that works without an admin's help and I have so far had no success working the methods described elsewhere. I got as far as the Grant Flow (since we are in an SSO environment) but the code that was returned was always rejected when I tried to get a token (The provided access grant is invalid, expired, or revoked (e.g. invalid assertion, expired authorization token, bad end-user password credentials, or mismatching authorization code and redirection URI))
Thanks for that feedback, KC. We've passed your comment on to the documentation team.
Thanks Nicole and Charles. That's perfect.
As a follow up to anyone else trying the Grant Flow, my issue turned out to be that the value for "redirection URI" that I was using didn't exactly match (missing a trailing slash) the value provided when I set up the Client. I suggest copying and pasting this value. I think it's less important what the value is than that it match exactly.
I'm a little confused. I hope it's just me not fully understanding things.
The premise of this article is to use an OAuth token for API calls so that those API calls are not associated with a specific user. But if an OAuth token is exchanged for a normal user/pass authorization, isn't the token associated with a specific user? That is, you, the requester?
I thought these tokens were unique to a user, so while the technique of generating a token without setting up a whole OAuthed app is helpful, I read this article on the presumption that I could "build... an internal application" where I do "not want your API requests to be associated with a specific user". Quotes from the very first sentence of this article.
Am I misunderstanding OAuth tokens? Or the intent of this article?
I see what you mean Dru. You're right. There is no "non-user" or system-type OAuth token. They are always associated with a user. I'm going to guess at the author's intent combined with what other customers have done, which is to create an "robo" agent that these tokens are created under. When the token is used, it's not against a particular user and no passwords have to be exposed.
You also gain the benefit of being able to revoke the tokens under this special user without affecting actual users. Since the title of the article is to create tokens for testing, this scenario might fit better.
Please sign in to leave a comment.