OAuth Tokens for Grant Types

This API consists of the Create Token for Grant Type endpoint. Use this endpoint to get access tokens for the following OAuth grant types:

• Authorization code grant type
• Password credentials grant type

The endpoint is not used with the implicit grant type because the access token is sent immediately in the redirect URL if the end user grants access. See Tokens for Implicit Grant Type.

For more information on the supported OAuth grant types, see Using OAuth authentication with your application in Help Center.

If you're not working with grant types, use the Create Token endpoint in the OAuth Tokens API. The two APIs don't share the same path, JSON format, or request parameters. However, both APIs return access tokens that can be used to authenticate API requests.

JSON format

OAuth Tokens for Grant Types are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
access_token	string	true	false	The access token
scope	string	true	false	The valid scopes for this token. See Scope below
token_type	string	true	false	Type of the access token, for example "bearer"

Example

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "scope": "read",
  "token_type": "bearer"
}

Create Token for Grant Type

• POST /oauth/tokens

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

• an authorization code valid for 120 seconds
• a Zendesk username and password

Refresh tokens aren't used. An access token doesn't expire but it can be revoked. Use the OAuth Tokens API to list, show, or revoke tokens.

Request parameters

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

Name	Description
grant_type	One of "authorization_code" or "password"
code	Authorization grant flow only. The authorization code you received from Zendesk after the user granted access. See Handle the user's authorization decision in Help Center
client_id	The Unique Identifier specified in an OAuth client in the Support admin interface (Admin > Channels > API > OAuth Clients). See Registering your application with Zendesk
client_secret	The Secret specified in an OAuth client in the Support admin interface (Admin > Channels > API > OAuth Clients). See Registering your application with Zendesk
redirect_uri	Authorization grant flow only. The redirect URL you specified when you sent the user to the Zendesk authorization page. For ID purposes only. See Send the user to the Zendesk authorization page
scope	Valid scope for this token. A string of space-separated values. See Scope below

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 calls the same endpoint as the authorization code grant flow (https://{subdomain}.zendesk.com/oauth/authorizations/new). However, it differs in that the access token is sent immediately in the redirect URL if the end user grants access. The token is not created with the Create Token for Grant Type endpoint.

See Implicit grant flow in Using OAuth authentication with your application in Help Center.

Code Samples

curl

Authorization code grant

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "authorization_code", "code": "7xqwtlf3rrdj8uyeb1yf",
    "client_id": "acme_rockets", "client_secret": "77f9931747b63f720f9fbc6",
    "redirect_uri": "https://www.example.com/app/grant_decision",
    "scope": "organizations:write read" }' \
  -X POST

curl

Password grant

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "password",  "client_id": "acme_rockets",
    "client_secret": "77f9931747b63f720f9fbc6",
    "username": "[email protected]", "password": "r23ssfoal",
    "scope": "organizations:write read" }' \
  -X POST

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/oauth/tokens"
	method := "POST"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/oauth/tokens")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("POST", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'POST',
  url: 'https://support.zendesk.com/oauth/tokens',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/oauth/tokens"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"POST",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/oauth/tokens")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

201 Created

// Status 201 Created

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "scope": "organizations:write read",
  "token_type": "bearer"
}