OAuth Tokens

OAuth tokens are credentials used to authenticate API requests on behalf of users or applications.

Note: The Create Token (POST /api/v2/oauth/tokens) endpoint is no longer available. To create OAuth access tokens, use Create Token for Grant Type instead. This endpoint supports OAuth grant types including authorization code, refresh token, and client credentials.

JSON format

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

Name	Type	Read-only	Mandatory	Description
client_id	integer	true	false	The id of the client this token belongs to
created_at	string	true	false	The time the token was created
expires_at	string	true	false	The time the token will expire
id	integer	true	false	Automatically assigned upon creation
refresh_token	string	true	false	The refresh token, if generated
refresh_token_expires_at	string	true	false	The time the refresh token will expire
scopes	array	true	false	An array of the valid scopes for this token. See Scopes below
token	string	true	false	The access token
url	string	true	false	The API url of this record
used_at	string	true	false	The latest time this token was used for authentication
user_id	integer	true	false	The id of the user this token authenticates as

Example

{
  "client_id": 41,
  "created_at": "2009-05-13T00:07:08Z",
  "expires_at": "2011-07-22T00:11:12Z",
  "id": 1,
  "refresh_token": "af3t24tfj34h43s...",
  "refresh_token_expires_at": "2011-07-22T00:11:12Z",
  "scopes": [
    "read"
  ],
  "token": "af3t24tfj34h43s...",
  "url": "https://example.zendesk.com/api/v2/tokens/1",
  "used_at": "2010-01-22T00:11:12Z",
  "user_id": 29
}

List Tokens

• GET /api/v2/oauth/tokens

Returns the properties of the tokens for the current user. Admins can view OAuth token properties for all users using the all parameter. To filter the list by OAuth client, use the client_id parameter for a local OAuth client ID, or the global_client_id parameter for a global OAuth client ID. For security reasons, only the first 10 characters of each access token are included.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
all	boolean	Query	false	A boolean that returns all OAuth tokens in the account. Requires admin role
client_id	integer	Query	false	The id of the OAuth client
global_client_id	integer	Query	false	The id of the global OAuth client
page	object	Query	false	Cursor-based pagination parameters (JSON:API style). Supports nested parameters: - page[size] - Number of records per page (default varies by endpoint, typically 100) - page[after] - Cursor token to fetch records after this position - page[before] - Cursor token to fetch records before this position Example: ?page[size]=50&page[after]=eyJvIjoiaWQiLCJ2IjoiYVFFPSJ9
sort	string	Query	false	Field to sort results by. Prefix with - for descending order. When used with cursor pagination, this determines the cursor ordering. Example: ?sort=name or ?sort=-created_at

Code Samples

curl

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

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/oauth/tokens?all=true&client_id=223443&global_client_id=334556&page=&sort=name"
	method := "GET"
	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 "{email_address}/token:{api_token}"

	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://example.zendesk.com/api/v2/oauth/tokens")
		.newBuilder()
		.addQueryParameter("all", "true")
		.addQueryParameter("client_id", "223443")
		.addQueryParameter("global_client_id", "334556")
		.addQueryParameter("page", "")
		.addQueryParameter("sort", "name");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/oauth/tokens',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  params: {
    'all': 'true',
    'client_id': '223443',
    'global_client_id': '334556',
    'page': '',
    'sort': 'name',
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/oauth/tokens?all=true&client_id=223443&global_client_id=334556&page=&sort=name"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"GET",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/oauth/tokens")
uri.query = URI.encode_www_form("all": "true", "client_id": "223443", "global_client_id": "334556", "page": "", "sort": "name")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

{
  "tokens": [
    {
      "client_id": 41,
      "created_at": "2009-05-13T00:07:08Z",
      "expires_at": "2011-07-22T00:11:12Z",
      "id": 223443,
      "refresh_token": "af3t24tfj34h43s...",
      "scopes": [
        "read"
      ],
      "token": "af3345kdj3",
      "url": "https://example.zendesk.com/api/v2/tokens/223443",
      "used_at": "2010-01-22T00:11:12Z",
      "user_id": 29
    },
    {
      "client_id": 41,
      "created_at": "2009-05-13T00:07:08Z",
      "expires_at": "2011-07-22T00:11:12Z",
      "id": 8678530,
      "refresh_token": "af3t24tfj34h43s...",
      "scopes": [
        "read"
      ],
      "token": "34hjgkjas4",
      "url": "https://example.zendesk.com/api/v2/tokens/8678530",
      "used_at": "2010-01-22T00:11:12Z",
      "user_id": 29
    }
  ]
}

Show Token

• GET /api/v2/oauth/tokens/{oauth_token_id}

Returns the properties of the specified token. For security reasons, only the first 10 characters of the access token are included.

In the first endpoint, id is a token id, not the full token.

In the second endpoint, include an Authorization: Bearer header with the full token to get its associated properties. Example:

curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens/current \
  -H 'Authorization: Bearer ${authToken}' \
  -v -u {email_address}/token:{api_token}

Allowed for

• Admins, Agents, End Users

Parameters

Name	Type	In	Required	Description
oauth_token_id	integer	Path	true	The ID of the OAuth token

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens/{oauth_token_id} \
  -H "Authorization: Bearer {access_token}"

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/oauth/tokens/223443"
	method := "GET"
	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 "{email_address}/token:{api_token}"

	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://example.zendesk.com/api/v2/oauth/tokens/223443")
		.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/oauth/tokens/223443',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/oauth/tokens/223443"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"GET",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/oauth/tokens/223443")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

{
  "token": {
    "client_id": 1234,
    "created_at": "2009-05-13T00:07:08Z",
    "expires_at": "2011-07-22T00:11:12Z",
    "id": 223443,
    "refresh_token": "af3t24tfj34h43s...",
    "scopes": [
      "read",
      "write"
    ],
    "token": "af3345kdj3",
    "url": "https://example.zendesk.com/api/v2/tokens/223443",
    "used_at": "2010-01-22T00:11:12Z",
    "user_id": 29
  }
}

Show Current Token

• GET /api/v2/oauth/tokens/current

Returns the properties of the current token. Include an Authorization: Bearer header with the full token to get its associated properties.

For security reasons, only the first 10 characters of the access token are included.

Allowed for

• Admins, Agents, End Users

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens/current \
  -H 'Authorization: Bearer ${authToken}' \
  -H "Authorization: Bearer {access_token}"

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/oauth/tokens/current"
	method := "GET"
	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 "{email_address}/token:{api_token}"

	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://example.zendesk.com/api/v2/oauth/tokens/current")
		.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/oauth/tokens/current',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/oauth/tokens/current"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"GET",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/oauth/tokens/current")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

{
  "token": {
    "client_id": 1234,
    "created_at": "2009-05-13T00:07:08Z",
    "expires_at": "2011-07-22T00:11:12Z",
    "id": 223443,
    "refresh_token": "af3t24tfj34h43s...",
    "scopes": [
      "read",
      "write"
    ],
    "token": "af3345kdj3",
    "url": "https://example.zendesk.com/api/v2/tokens/223443",
    "used_at": "2010-01-22T00:11:12Z",
    "user_id": 29
  }
}

Revoke Token

• DELETE /api/v2/oauth/tokens/{oauth_token_id}

Allowed for

• Admins, Agents, End Users

Parameters

Name	Type	In	Required	Description
oauth_token_id	integer	Path	true	The ID of the OAuth token

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens/{oauth_token_id} \
  -X DELETE -H "Authorization: Bearer {access_token}"

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/oauth/tokens/223443"
	method := "DELETE"
	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 "{email_address}/token:{api_token}"

	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://example.zendesk.com/api/v2/oauth/tokens/223443")
		.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://example.zendesk.com/api/v2/oauth/tokens/223443',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/oauth/tokens/223443"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"DELETE",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/oauth/tokens/223443")
request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

204 No Content

// Status 204 No Content

null

Revoke Current Token

• DELETE /api/v2/oauth/tokens/current

Revokes the current OAuth token. Include an Authorization: Bearer header with the full token.

Allowed for

• Admins, Agents, End Users

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens/current \
  -H 'Authorization: Bearer ${authToken}' \
  -X DELETE -H "Authorization: Bearer {access_token}"

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/oauth/tokens/current"
	method := "DELETE"
	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 "{email_address}/token:{api_token}"

	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://example.zendesk.com/api/v2/oauth/tokens/current")
		.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://example.zendesk.com/api/v2/oauth/tokens/current',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/oauth/tokens/current"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"DELETE",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/oauth/tokens/current")
request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

204 No Content

// Status 204 No Content

null