Creating and using OAuth tokens with the API

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:

• Quickly creating a token with the API console
• Creating a token with the Zendesk API
• Use the token in requests

Warning: An OAuth access token is like a password. Keep it secure. If at any time you suspect a token has been compromised, revoke it at once. See Revoke Token.

Quickly creating a token with the API console

The quickest, easiest way to get an OAuth token is to use the API console on developer.zendesk.com.

You'll need a Zendesk username and password to use this method. If your organization uses single sign-on (SSO) and the Zendesk passwords were deleted from the Zendesk account, then you'll have to use the second method, Creating a token with the Zendesk API.

To create an OAuth access token

1. Go to the the API console on developer.zendesk.com.

2. Make sure OAuth2 Implicit Grant is selected, then enter the subdomain of your Support account in the field next to the Authorize button.

   Example:

   

3. Click Authorize.

4. If prompted, sign in to your Zendesk account as usual.

   If you're already signed in with your browser, you won't be prompted to sign in.

5. At the prompt, allow the API console to access your Zendesk account.

   

   Back in the console, your access token appears next to the Authorize button.

   

6. Double-click anywhere in the token to select all of it, copy it to your Clipboard, and save it in a safe place.

   Be especially careful about including the token in your client-side code, where it can be read by anybody. Have the user get the token and store it as a data item in their browser's localStorage object. For details, see Making cross-origin, browser-side API requests.

Creating a token with the Zendesk API

The section describes the steps to create an OAuth access token with the Zendesk API:

1. Create an OAuth client
2. Get the id of the new client
3. Use the client id to get an access token

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

1. In Zendesk Support, select Admin > Channels > API > OAuth Clients.
2. 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.

Note: If the admin's role is later changed to agent or end user, then the token's access permissions will also be changed to that of the new role. For example, it will no longer work with endpoints that are only allowed for 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.