Getting an OAuth access token for testing purposes

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.

Important: The technique described in this article basically consists in exchanging a Zendesk username and password for an access token. As a result, the token has the same security vulnerabilities as a password. Anybody with the token has access to the account. Keep the token in a safe place and don't hard-code it in your application code. Store it in an environment variable instead.

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"