Security and authentication

You must be a verified user to make API requests. You can authorize against the API using either basic authentication with your email address and password, with your email address and an API token, or with an OAuth access token.

Client-side CORS requests are supported if the request is authenticated with an OAuth access token. The requests are not supported if the request uses basic authentication or a Zendesk API token. For more information and a tutorial, see Making cross-origin, browser-side API requests.

Topics covered in this section:

• Basic authentication
• API token
• OAuth access token
• SSL requirements

Basic authentication

You can use your email address and password to access the API. The credentials must be sent in an Authorization header in the HTTP request. Credentials sent in the body or URL of the request are ignored.

To use basic authentication, password access must be enabled in the Admin Center interface at Apps and integrations > APIs > Zendesk API.

To authenticate a request with basic authentication

1. Combine your email address and password with a colon. Example: [email protected]:pa$$w0rd.

2. Base64-encode the resulting string. Example: amRvZUBleGFtcGxlLmNvbTpwYSQkdzByZA==.

3. Include the base64-encoded string in a HTTP Authorization header as follows:

   Authorization: Basic {base64-encoded-string}

   Example:

   Authorization: Basic amRvZUBleGFtcGxlLmNvbTpwYSQkdzByZA==

Note: Most HTTP request libraries have methods that simplify basic authentication.

To learn more, see Authentication for API requests in the Support Help Center.

If you use curl to test different endpoints, you can use the following format:

curl https://obscura.zendesk.com/api/v2/users.json \
  -u [email protected]:pa\$\$w0rd

If an agent or admin has enabled 2-factor authentication in their user profile, they won't be able to use basic authentication. Alternatives include using an API token or implementing an OAuth flow. Learn more.

API token

API tokens are different from OAuth tokens, which are detailed in the next section. API tokens are auto-generated passwords in the Support admin interface.

Warning: As passwords, API tokens can be used to impersonate anyone in the account, including admins. Make sure to keep them secure. Delete any unused tokens. Delete a token at once if you suspect it's been compromised and create another one if necessary. Another option is to use OAuth tokens, which are described in the next section.

API tokens are managed in the Admin Center interface at Apps and integrations > APIs > Zendesk API. The page lets you view, add, or delete tokens. More than one token can be active at the same time. Deleting a token deactivates it permanently.

Basic authentication is used for API tokens. As described in Basic authentication above, the credentials must be sent with the request in an Authorization header.

Use the following format for the credentials:

{email_address}/token:{api_token}

Example:

[email protected].com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

After base64-encoding the resulting string, add it to the Authorization header as follows:

Authorization: Basic amRvZUBleGFtcGxlLmNvbS90b2tlbjo2d2lJQldiR2tCTW8xbVJETXVWd2t3MUVQc05rZVVqOTVQSXoyYWt2

If you use curl to test different endpoints, you can use the following format:

curl https://obscura.zendesk.com/api/v2/users.json \
  -u [email protected]/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

If authenticating over HTTP, url-encode the slash character in {email_address}/token as %2F.

OAuth access token

The Zendesk API supports OAuth authorization flows. Learn more.

OAuth access tokens also permit client-side API requests. See Making cross-origin, browser-side API requests in the Zendesk API guide.

In your requests, specify the access token in an Authorization header as follows:

Authorization: Bearer {access_token}

Example:

Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo

If you use curl to test different endpoints, you can use the following format:

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

SSL requirements

The Zendesk v2 API an SSL-only API, regardless of how your account is configured.

All connections to the Zendesk API must support the TLS 1.2 protocol. Support for TLS 1.0 and 1.1 was removed in June 2018.

Connections to the API must also support the SNI extension to TLS.

If you connect to Zendesk through a client library, make sure it supports both TLS 1.2 and SNI.