Content last updated 2025-12-23

API

Documentation on Zendesk API

Understanding Zendesk API

What is Zendesk API

The Zendesk Support API is a collection of Zendesk endpoints you can use to get various information or do various tasks. It is quite robust and something we use quite often.

What are Zendesk API tokens

Zendesk API tokens are used in authentication for Zendesk API requests. These tokens are always at the administrator level and cannot be issued at lower permission/role levels. As such, you should always use caution in using and issuing these tokens.

What are Zendesk integrations

Zendesk integrations are permanent connections between Zendesk and third-party services. Unlike API tokens which can be easily revoked, integrations are more deeply embedded in Zendesk’s configuration and are significantly harder to remove. Integrations should only be used for production systems that require persistent access.

API Rate Limits

Zendesk enforces rate limits on API requests. See Zendesk rate limits documentation for current limits and best practices.

Requesting an API token or integration

Both API tokens and integrations follow this approval process:

Submit Request: File an access request issue
Manager Approval: The requester’s manager must approve the request
Security Review: A Fullstack Engineer, Customer Support Operations reviews the business justification
Decision: If approved, the engineer will create the token or integration

Key Differences:

API Tokens: Created directly in Zendesk, shared via 1Password
Integrations: Created using Integration bot account, process varies by integration type

How to authenticate to the Zendesk API

Basic authentication

Note

The ability to do this is not enabled on our production Zendesk instances.

To authenticate using basic authentication, you’ll need to know your username (email) and password for your Zendesk account. With those in hand, you can either use those directly or encode the string into base64 (and use it in the headers).

Example of using it raw:

curl https://example.zendesk.com/api/v2/users.json \
  -u jcolyer@example.com:my_password

Example of using it via headers:

echo 'jcolyer@example.com:my_password' | base64
amNvbHllckBnaXRsYWIuY29tOm15X3Bhc3N3b3JkCg==

curl https://example.zendesk.com/api/v2/users.json \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tOm15X3Bhc3N3b3JkCg=="

API token authentication

To authenticate via an API token, you’ll need to know your username and the API token in question. With those in hand, you can either use those directly or encode the string into base64 (and use it in the headers). When using an API token, you must add /token after your username.

Example of using it raw:

curl https://example.zendesk.com/api/v2/users.json \
  -u jcolyer@example.com/token:api_token

Example of using it via headers:

echo 'jcolyer@example.com/token:api_token' | base64
amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo=

curl https://example.zendesk.com/api/v2/users.json \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

OAuth access token authentication

To use an OAuth access token, you’d first need to create an OAuth app in Zendesk (see Zendesk documentation for more information). With the access token in hand, you would pass this into the headers.

curl https://example.zendesk.com/api/v2/users.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

How to use the Zendesk API

Note

This focuses solely on the Zendesk API via curl. For more information on using a library, check out the corresponding library’s documentation.

To get started, you would need to know the endpoint you wish to use. Generally speaking, the most common ones you might use for quick actions are:

For more administrative tasks, the common ones you might use are:

Once you have determined what you wish to do, go to the corresponding API endpoint documentation and make note of:

The request type
- GET
- POST
- PUT
- PATCH
- DELETE
The endpoint URL
Any required parameters

From there, you will craft a curl command in the format of:

curl ZENDESK_URL/api/v2/ENDPOINT \
  -X REQUEST_TYPE \
  -H HEADER_INFO \
  -u AUTHENTICATION \
  -d DATA_TO_USE

Where:

ZENDESK_URL is the URL of the Zendesk instance
ENDPOINT is the endpoint to use
-X REQUEST_TYPE is the request type from the documentation (not needed if making a GET request)
-H HEADER_INFO is any needed header information (not always needed)
-u AUTHENTICATION is the user/pass or user/token combo (not needed if using header based authentication)
-d DATA_TO_USE is the data to send with the request (not always needed)

As an example, if you wanted to get the details for automation 12345, your curl command might look like:

curl https://example.zendesk.com/api/v2/automations/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Likewise, if you wanted to update automation 12345 to set active to false (i.e. deactivate it), your curl command might look like:

curl https://example.zendesk.com/api/v2/automations/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo=" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"automation": {"active": false}}'

If we wanted to delete automation 12345, your curl command might look like:

curl https://example.zendesk.com/api/v2/automations/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo=" \
  -H "Content-Type: application/json" \
  -X DELETE

Administrator tasks

Danger

Security Considerations:

All Zendesk API tokens are admin-level and extremely dangerous. Issue only when absolutely necessary.
Integrations are significantly harder to revoke than API tokens and pose higher security risks.

Requirements:

Integrations must be created via the Integration bot agent account.
Integration requests for Zendesk US Government are not currently supported due to security requirements.

Token creation requests

Important

The token description in Zendesk must be the URL of the access request issue for tracking and auditing purposes.

All requests for an API token should be done via an access request issue.

There are two exceptions to this:

API tokens for Customer Support Operations team members’ personal use
API tokens for Support Operations scripts/automations/etc.

Once an access request is filed, the requester’s manager must approve the request.

After that has been done, the provisioner for the instance (traditionally a Fullstack Engineer, Customer Support Operations) will review the request.

During this review, we carefully review the business reasons and use-case of each request due to the significant access level that an API token provides.

If deemed acceptable, the Fullstack Engineer, Customer Support Operations will then create the API token. To create the API token:

Navigate to the admin dashboard for the Zendesk instance
Navigate to Apps and integrations > APIs > API tokens
Click Add API token in the top-right of the page
Enter a description (remember, it should be the access request issue’s URL)
Click Save
Copy the token in the Token field
Click Save once again

The API token will then be shared with the requester via a one-time accessible 1Password item.

Integration requests

All requests for an integration should be done via an access request issue.

Once an access request is filed, the requester’s manager must approve the request.

After that has been done, the provisioner for the instance (traditionally a Fullstack Engineer, Customer Support Operations) will review the request.

During this review, we carefully analyze the business reasons and use-case due to the significant access level that integrations provide. Integrations pose even higher risks and should be avoided whenever possible. While API tokens can be quickly and easily revoked, integrations cannot.

If deemed acceptable, the Fullstack Engineer, Customer Support Operations will then create the integration.

The exact means for this will vary by integration type. Refer to the specific integration’s documentation for setup steps. All integrations must be created using the Integration bot account for the Zendesk instance to ensure proper tracking and revocation capabilities.

Revoking an API token

To revoke an API token:

Navigate to the admin dashboard for the Zendesk instance
Navigate to Apps and integrations > APIs > API tokens
Locate the token in question and click the three vertical dots (at the far right of the token entry)
Click Deactivate
Confirm the revocation by clicking Deactivate in the pop-up box

Revoking an integration

Specifics cannot be provided here as it will vary from integration to integration.

Last modified January 21, 2026: Revamp CustSuppOps handbook (7d49549f)

View page source - Edit this page - please contribute.