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
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 Admin Center interface at Apps and integrations > APIs > Zendesk API.
To authenticate a request with basic authentication
-
Combine your email address and password with a colon. Example:
[email protected]:pa$$w0rd. -
Base64-encode the resulting string. Example:
amRvZUBleGFtcGxlLmNvbTpwYSQkdzByZA==. -
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 Zendesk help.
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 your organization uses single sign-on (SSO) or two-factor authentication is enabled in your user profile, you can't use basic authentication. Use an API token or an OAuth access token instead.
API token
API tokens are different from OAuth tokens, which are detailed in the next section. API tokens are auto-generated passwords in the Zendesk Admin Center.
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:
jdoe@example.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.