Using the API when SSO or two-factor authentication is enabled

If your organization uses single sign-on (SSO) or two-factor authentication is enabled in your user profile, you can't use your Zendesk email address and password to authenticate Zendesk API requests. Instead, you can authenticate requests using an API token or an OAuth access token.

Using an API token

Instead of a password, you can use an API token with your Zendesk email address to authorize Zendesk API requests using basic authentication. Unlike a password, an API token isn't tied to a specific user. You can use the token with the email address of any admin, agent, or other valid user.

When passing an API token, format the credentials as follows:

{email_address}/token:{api_token}

Example:

curl https://example.zendesk.com/api/v2/users.json
  -u [e-mail]/token:6wiIBWbGkBMo1mRDMuVwsNkeUj95PIz2akv

To create an API token, see Generating a new API token in Zendesk help. For more details on passing the token in API requests, see API token in the API reference.

Use API tokens in the following cases:

• Example requests from the API reference
• Internal scripts that rely on a user name and password to make API requests

Using an OAuth access token

You can also authenticate Zendesk API requests using an OAuth access token. Unlike API tokens, OAuth tokens are tied to a specific user and use scopes to limit access to a Zendesk account.

Developers often use OAuth access tokens to authenticate Zendesk API requests on behalf of their users. This involves building an OAuth authorization flow that requires interaction from the user. For an example of this setup, see Using OAuth to authenticate Zendesk API requests in a web app.

You can also create and use OAuth access tokens on your own behalf without building an authorization flow. For more information, see Creating and using OAuth tokens with the API.

Use OAuth access tokens in the following cases:

• Apps that require per-user authentication
• Apps developed by any third-party developers