How to Set Up Your First Zendesk API Token in 5 Minutes

Overview of Authentication Methods

Zendesk API offers two primary methods for authentication:

• OAuth Access Token: Preferred for user-based authentication, requiring user interaction to create.

• API Token: Simpler, primarily used for personal or developer access.

Advantages of OAuth Access Tokens

• Scoped Access: OAuth tokens use scopes that limit access to functionalities within Zendesk.

• Revocation Ease: Easily revocable for enhanced security.

Creating an OAuth Client

To generate an OAuth access token, you first need an OAuth client. Two methods to create it include:

1. Using Admin Center: Requires admin sign-in. Redirect URLs are not needed for token creation.

2. API Request: Use Create Client API to establish an OAuth client directly through a request.

Example API Request

curl https://{subdomain}.zendesk.com/api/v2/oauth/clients.json \
-X POST \
-u {email_address}/token:{api_token} \
-H "Content-Type: application/json" \
-d '{
  "client": {
    "name": "Test client",
    "identifier": "test_client",
    "kind": "public"
  }
}'

Getting the OAuth Client ID

To create an access token, the client's ID is necessary. This can be retrieved using the List Clients request if not already known.

Example API Request

curl https://{subdomain}.zendesk.com/api/v2/oauth/clients.json \
-u {email_address}/token:{api_token}

Creating the Access Token

Once the OAuth client is in place, create an access token using the Create Token request, which must include the following parameters:

• client_id: The ID of the OAuth client.

• scopes: The permissions associated with the token.

Example API Request

curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json \
-X POST \
-u {email_address}/token:{api_token} \
-H "Content-Type: application/json" \
-d '{
  "token": {
    "client_id": 223443,
    "scopes": ["tickets:read"]
  }
}'

The response includes the full_token, which must be kept secure.

Token Management

Consider implementing mechanisms to handle token expiration and refresh processes. If an OAuth token becomes invalid, redirect users to initiate the authorization again.

Using the Access Token

Authenticate requests by including the access token in the Authorization header as a Bearer token.

Example API Request

curl https://{subdomain}.zendesk.com/api/v2/users.json \
-H "Authorization: Bearer {access_token}"

Conclusion

This guide applies specifically to generating OAuth access tokens outside the Sales CRM API, which has different OAuth requirements. By following these guidelines, developers can effectively secure their integrations with Zendesk's API.