Global OAuth Clients

This API returns information about Global OAuth Clients tied to your account. For a Global OAuth Client to be return from this API, there has to be some OAuth Token in your account which has that Global OAuth Client's ID tied to it. Global OAuth Clients are not mutatable as they are owned by third party developers or Zendesk. See Set up a global OAuth client to learn how to get one for development.

JSON format

Global OAuth Clients are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
company	string	true	false	The company that users are asked to approve access to
description	string	true	false	A short description of the client
id	integer	true	false	Automatically assigned when the client is created
identifier	string	true	false	The unique identifier for the client
kind	string	true	false	The kind of client, public or confidential
logo_url	string	true	false	The API logo url of this record
name	string	true	false	The name of the client

Example

{
  "company": "Zendesk",
  "description": "Zendesk global Client",
  "id": 1,
  "identifier": "global_client",
  "kind": "public",
  "logo_url": "https://example.com/logo",
  "name": "Global Client"
}

List Global OAuth Clients

• GET /api/v2/oauth/global_clients

Returns all the global OAuth clients that users on your account have authorized.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Admins
• Agents with the Manage APIs permission

Parameters

Name	Type	In	Required	Description
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/global_clients \
  -H "Authorization: Bearer {access_token}"

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/oauth/global_clients?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/global_clients")
		.newBuilder()
		.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/global_clients',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  params: {
    '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/global_clients?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/global_clients")
uri.query = URI.encode_www_form("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

{
  "global_clients": [
    {
      "company": "Zendesk",
      "description": "Stats Widget Global Client",
      "id": 223443,
      "identifier": "stats_widget",
      "kind": "public",
      "logo_url": "https://example.com/logo",
      "name": "Stats Widget"
    },
    {
      "company": "Zendesk",
      "description": "Zendesk App Global Client",
      "id": 8678530,
      "identifier": "zendesk_mobile_app",
      "kind": "public",
      "logo_url": "https://example.com/logo",
      "name": "Zendesk Mobile"
    }
  ]
}

Show Global OAuth Client

• GET /api/v2/oauth/global_clients/{global_client_id}

Returns the global OAuth client associated with the ID sent on the request.

Allowed for

• Admins
• Agents with the Manage APIs permission

Parameters

Name	Type	In	Required	Description
global_client_id	integer	Path	true	The ID of the Global OAuth client

Code Samples

curl

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

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/oauth/global_clients/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/global_clients/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/global_clients/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/global_clients/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/global_clients/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

{
  "global_client": {
    "company": "Zendesk",
    "description": "Stats Widget Global Client",
    "id": 223443,
    "identifier": "stats_widget",
    "kind": "public",
    "logo_url": "https://example.com/logo",
    "name": "Stats Widget"
  }
}

Show Token summary for Global OAuth Clients

• GET /api/v2/oauth/global_clients/token_summary

Returns information about tokens for the global clients that your account has authorized.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Admins
• Agents with the Manage APIs permission

Parameters

Name	Type	In	Required	Description
global_client_id	integer	Query	false	The id of the global OAuth client
include_expired	boolean	Query	false	If true, includes expired tokens in summary

Code Samples

curl

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

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/oauth/global_clients/token_summary?global_client_id=334556&include_expired=true"
	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/global_clients/token_summary")
		.newBuilder()
		.addQueryParameter("global_client_id", "334556")
		.addQueryParameter("include_expired", "true");
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/global_clients/token_summary',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  params: {
    'global_client_id': '334556',
    'include_expired': 'true',
  },
};

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/global_clients/token_summary?global_client_id=334556&include_expired=true"
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/global_clients/token_summary")
uri.query = URI.encode_www_form("global_client_id": "334556", "include_expired": "true")
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

{
  "global_clients": [
    {
      "id": 223443,
      "last_used_at": "2024-06-07T15:46:32Z",
      "tokens_count": 321
    },
    {
      "id": 223481,
      "last_used_at": "2024-08-07T15:46:32Z",
      "tokens_count": 123
    }
  ]
}