POST /oauth/tokens

Returns an OAuth access token in exchange for an authorization code valid for 120 seconds.

Using a Zendesk username and password to gain an OAuth access token (password grant type flow) has been deprecated and is highly discouraged.

An access token can be revoked. Use the OAuth Tokens API to list, show, or revoke tokens.

The refresh token grant type allows for refreshing an access token that has either expired or is about to expire. See Oauth Tokens for Grant Types.

Request parameters

The POST request takes the following parameters, which must be formatted as JSON:

Example Node.js authorization code grant flow

const tokenResponse = await axios.post(
  `https://${ZENDESK_SUBDOMAIN}.zendesk.com/oauth/tokens`,
  {
    grant_type: "authorization_code",
    code: req.query.code,
    client_id: ZENDESK_CLIENT_ID,
    redirect_uri: REDIRECT_URI_PKCE,
    scope: "read write",
    code_verifier: CODE_VERIFIER,
    expires_in: 86400,
    refresh_token_expires_in: 604800,
  },
  { headers: { "Content-Type": "application/json" } }
);

Example Node.js refresh token grant flow

const tokenResponse = await axios.post(
  `https://${ZENDESK_SUBDOMAIN}.zendesk.com/oauth/tokens`,
  {
    grant_type: "refresh_token",
    refresh_token: refresh_token,
    client_id: ZENDESK_CLIENT_ID,
    client_secret: ZENDESK_CLIENT_SECRET,
    scopes: "tickets:write",
    expires_in: 86400,
    refresh_token_expires_in: 604800,
  },
  { headers: { "Content-Type": "application/json" } }
);

Scope

You must specify a scope to control the app's access to Zendesk resources. The "read" scope gives access to GET endpoints. It includes permission to sideload related resources. The "write" scope gives access to POST, PUT, and DELETE endpoints for creating, updating, and deleting resources.

Note: Don't confuse the scope parameter (singular) with the scopes parameter (plural) for non-grant-type tokens described in OAuth Tokens.

The "impersonate" scope allows a Zendesk admin to make requests on behalf of end users. See Making API requests on behalf of end users.

For example, the following parameter gives read access to all resources:

"scope": "read"

The following parameter gives read and write access to all resources:

"scope": "read write"

You can fine-tune the scope of the following resources:

• tickets
• users
• auditlogs (read only)
• organizations
• hc
• apps
• triggers
• automations
• targets
• webhooks

The syntax is as follows:

"scope": "resource:scope"

For example, the following parameter restricts the scope to only reading tickets:

"scope": "tickets:read"

To give read and write access to a resource, specify both scopes:

"scope": "users:read users:write"

To give write access only to one resource, such as organizations, and read access to everything else:

"scope": "organizations:write read"

Note: The endpoint returns an access token even if you specify an invalid scope such as "scope": ["read", "write"] (no parentheses). Any request you make with the token will return a "Forbidden" error.

Tokens for Implicit Grant Type

The implicit grant flow has been deprecated. It's considered insecure and its use is highly discouraged.

Servers

• https://{subdomain}.{domain}.com

How to start integrating

1. Add HTTP Task to your workflow definition.
2. Search for the API you want to integrate with and click on the name.
   • This loads the API reference documentation and prepares the Http request settings.
3. Click Test request to test run your request to the API and see the API's response.