POST /oauth/tokens

Returns an OAuth access token in exchange for one of the following:

• an authorization code
• a refresh token
• a client secret

Note: The password grant type flow, which used a Zendesk username and password to get an access token, has been deprecated and is highly discouraged.

To revoke an access token, see Revoke Token.

Request parameters

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

Authorization code example

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

Refresh token example

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

Client credentials example

const tokenResponse = await axios.post(
  "https://{subdomain}.zendesk.com/oauth/tokens",
  {
    grant_type: "client_credentials",
    client_id: ZENDESK_CLIENT_ID,
    client_secret: ZENDESK_CLIENT_SECRET,
    scope: "tickets:write",
    expires_in: 86400
  },
  { 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 and 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.

Broad scopes

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"

Resource-specific scopes

You can fine-tune access using resource-specific scopes. The syntax is as follows:

"scope": "resource:action"

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"

Scope errors

There are two distinct scope-related error cases to be aware of:

• Unrecognized scope string: If you specify a scope value that doesn't exist (for example, a typo such as "scope": ["read", "write"] using an array instead of a string), the endpoint still creates an access token. However, any API request made with that token will return a 403 Forbidden error.
• Scope outside client's allowed scopes: If the OAuth client has allowed scopes configured and you request a scope not included in that list, the endpoint returns 400 Bad Request with an invalid_scope error and no token is created.

Available scopes

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.