OAuth Clients

Stores and manages OAuth clients for an integration. You use an OAuth client to create an OAuth connection. See Creating and managing OAuth connections

Authentication

You can authorize requests to OAuth Clients endpoints using a ZIS OAuth access token. A Zendesk app can also authorize requests to these endpoints using an admin's browser session. See Making API requests from a Zendesk app.

JSON format

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

Name	Type	Read-only	Mandatory	Description
auth_url	string	false	false	The authorization URL of the OAuth provider
client_id	string	false	true	The client secret obtained from your OAuth provider
client_secret	string	false	true	The client secret obtained from your OAuth Provider
created_at	string	true	false	When the OAuth client was created
created_by	string	true	false	User who created the connection
default_scopes	string	false	false	A set of case-sensitive and space-delimited OAuth scopes
grant_type	string	false	false	Default grant type for the client's OAuth flows. Valid values are "authorization_code" and "client_credentials". Defaults to "authorization_code"
integration	string	false	false	The name of the integration.
token_url	string	false	true	The token URL of the OAuth provider to exchange for an access token
updated_at	string	true	false	When the OAuth client was updated
uuid	string	true	false	The UUID of the OAuth client

Show OAuth Clients

• GET /api/services/zis/connections/oauth/clients/{integration}

Returns all OAuth clients for a ZIS integration.

Parameters

Name	Type	In	Required	Description
integration	string	Path	true	Name of the integration

Code Samples

cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/clients/{integration} \
-H "Authorization: Bearer {access_token}"

Go

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

func main() {
	url := "https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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/api/services/zis/connections/oauth/clients/my_integration")
		.newBuilder();

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

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration',
  headers: {
	'Content-Type': 'application/json',
  },
};

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/api/services/zis/connections/oauth/clients/my_integration"
headers = {
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
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

{
  "clients": [
    {
      "auth_url": "https://client.int/auth",
      "client_id": "my_client_id",
      "client_secret": "my_client_secret",
      "created_at": "2023-06-22T06:36:31Z",
      "created_by": "test_user",
      "default_scopes": "read write",
      "grant_type": "authorization_code",
      "integration": "my_integration",
      "token_url": "https://client.int/tokens",
      "updated_at": "2023-06-22T06:36:31Z",
      "uuid": "2fea765a-5ae4-4e3b-b457-a4f7836d041b"
    }
  ]
}

401 Unauthorized

// Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1200",
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "1200",
      "detail": "Forbidden",
      "status": "403"
    }
  ]
}

429 Too Many Requests

// Status 429 Too Many Requests

{
  "errors": [
    {
      "code": "1300",
      "detail": "Too many requests",
      "status": "429"
    }
  ]
}

Create OAuth Client

• POST /api/services/zis/connections/oauth/clients/{integration}

Creates an OAuth client.

Parameters

Name	Type	In	Required	Description
integration	string	Path	true	Name of the integration

Example body

{
  "auth_url": "https://client.int/auth",
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "default_scopes": "read write",
  "grant_type": "authorization_code",
  "name": "my_oauth_client_name",
  "token_url": "https://client.int/tokens"
}

Code Samples

cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/clients/{integration} \
-H "Authorization: Bearer {access_token}" \
-X POST \
-H 'content-type: application/json' \
-d '{
  "auth_url": "https://client.int/auth",
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "grant_type": "authorization_code",
  "default_scopes": "read write",
  "name": "my_oauth_client",
  "token_url": "https://client.int/tokens"
}'

Go

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

func main() {
	url := "https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration"
	method := "POST"
	payload := strings.NewReader(`{
  "auth_url": "https://client.int/auth",
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "default_scopes": "read write",
  "grant_type": "authorization_code",
  "name": "my_oauth_client_name",
  "token_url": "https://client.int/tokens"
}`)
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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/api/services/zis/connections/oauth/clients/my_integration")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"auth_url\": \"https://client.int/auth\",
  \"client_id\": \"my_client_id\",
  \"client_secret\": \"my_client_secret\",
  \"default_scopes\": \"read write\",
  \"grant_type\": \"authorization_code\",
  \"name\": \"my_oauth_client_name\",
  \"token_url\": \"https://client.int/tokens\"
}""");

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

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "auth_url": "https://client.int/auth",
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "default_scopes": "read write",
  "grant_type": "authorization_code",
  "name": "my_oauth_client_name",
  "token_url": "https://client.int/tokens"
});

var config = {
  method: 'POST',
  url: 'https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration',
  headers: {
	'Content-Type': 'application/json',
  },
  data : data,
};

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

Python

import requests
import json

url = "https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration"

payload = json.loads("""{
  "auth_url": "https://client.int/auth",
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "default_scopes": "read write",
  "grant_type": "authorization_code",
  "name": "my_oauth_client_name",
  "token_url": "https://client.int/tokens"
}""")
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"POST",
	url,
	headers=headers,
	json=payload
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
  "auth_url": "https://client.int/auth",
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "default_scopes": "read write",
  "grant_type": "authorization_code",
  "name": "my_oauth_client_name",
  "token_url": "https://client.int/tokens"
})
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

{
  "uuid": "2fea765a-5ae4-4e3b-b457-a4f7836d041b"
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "1301",
      "detail": "Invalid request",
      "status": "400"
    }
  ]
}

401 Unauthorized

// Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1200",
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "1200",
      "detail": "Forbidden",
      "status": "403"
    }
  ]
}

422 Unprocessable Entity

// Status 422 Unprocessable Entity

{
  "errors": [
    {
      "code": "1303",
      "detail": "Invalid value for: Integration. Desc: Integration cannot be nil",
      "status": "422"
    }
  ]
}

429 Too Many Requests

// Status 429 Too Many Requests

{
  "errors": [
    {
      "code": "1300",
      "detail": "Too many requests",
      "status": "429"
    }
  ]
}

Show OAuth Client

• GET /api/services/zis/connections/oauth/clients/{integration}/{client_uuid}

Return details for an OAuth client.

Parameters

Name	Type	In	Required	Description
client_uuid	string	Path	true	The UUID of the OAuth client
integration	string	Path	true	Name of the integration

Code Samples

cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/clients/{integration}/{client_uuid} \
-H "Authorization: Bearer {access_token}"

Go

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

func main() {
	url := "https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b")
		.newBuilder();

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

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b',
  headers: {
	'Content-Type': 'application/json',
  },
};

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/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b"
headers = {
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
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

{
  "auth_url": "https://client.int/auth",
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "created_at": "2023-06-22T06:36:31Z",
  "created_by": "test_user",
  "default_scopes": "read write",
  "grant_type": "authorization_code",
  "integration": "my_integration",
  "token_url": "https://client.int/tokens",
  "updated_at": "2023-06-22T06:36:31Z",
  "uuid": "2fea765a-5ae4-4e3b-b457-a4f7836d041b"
}

401 Unauthorized

// Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1200",
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "1200",
      "detail": "Forbidden",
      "status": "403"
    }
  ]
}

404 Not Found

// Status 404 Not Found

{
  "errors": [
    {
      "code": "1302",
      "detail": "Not found",
      "status": "404"
    }
  ]
}

429 Too Many Requests

// Status 429 Too Many Requests

{
  "errors": [
    {
      "code": "1300",
      "detail": "Too many requests",
      "status": "429"
    }
  ]
}

Update OAuth Client

• PATCH /api/services/zis/connections/oauth/clients/{integration}/{client_uuid}

Updates an OAuth client.

Parameters

Name	Type	In	Required	Description
client_uuid	string	Path	true	The UUID of the OAuth client
integration	string	Path	true	Name of the integration

Example body

{
  "auth_url": "https://client.int/auth",
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "default_scopes": "read write",
  "grant_type": "authorization_code",
  "token_url": "https://client.int/tokens"
}

Code Samples

cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/clients/{integration}/{client_uuid} \
-H "Authorization: Bearer {access_token}" \
-X PATCH \
-H 'content-type: application/json' \
-d '{
  "auth_url": "https://client.int/auth",
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "grant_type": "authorization_code",
  "default_scopes": "read write",
  "token_url": "https://client.int/tokens"
}'

Go

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

func main() {
	url := "https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b"
	method := "PATCH"
	payload := strings.NewReader(`{
  "auth_url": "https://client.int/auth",
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "default_scopes": "read write",
  "grant_type": "authorization_code",
  "token_url": "https://client.int/tokens"
}`)
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"auth_url\": \"https://client.int/auth\",
  \"client_id\": \"my_client_id\",
  \"client_secret\": \"my_client_secret\",
  \"default_scopes\": \"read write\",
  \"grant_type\": \"authorization_code\",
  \"token_url\": \"https://client.int/tokens\"
}""");

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

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "auth_url": "https://client.int/auth",
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "default_scopes": "read write",
  "grant_type": "authorization_code",
  "token_url": "https://client.int/tokens"
});

var config = {
  method: 'PATCH',
  url: 'https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b',
  headers: {
	'Content-Type': 'application/json',
  },
  data : data,
};

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

Python

import requests
import json

url = "https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b"

payload = json.loads("""{
  "auth_url": "https://client.int/auth",
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "default_scopes": "read write",
  "grant_type": "authorization_code",
  "token_url": "https://client.int/tokens"
}""")
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"PATCH",
	url,
	headers=headers,
	json=payload
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b")
request = Net::HTTP::Patch.new(uri, "Content-Type": "application/json")
request.body = %q({
  "auth_url": "https://client.int/auth",
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "default_scopes": "read write",
  "grant_type": "authorization_code",
  "token_url": "https://client.int/tokens"
})
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

{
  "auth_url": "https://client.int/auth",
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "created_at": "2023-06-22T06:36:31Z",
  "created_by": "test_user",
  "default_scopes": "read write",
  "grant_type": "authorization_code",
  "integration": "my_integration",
  "token_url": "https://client.int/tokens",
  "updated_at": "2023-06-22T06:36:31Z",
  "uuid": "2fea765a-5ae4-4e3b-b457-a4f7836d041b"
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "1301",
      "detail": "Invalid request",
      "status": "400"
    }
  ]
}

401 Unauthorized

// Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1200",
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "1200",
      "detail": "Forbidden",
      "status": "403"
    }
  ]
}

404 Not Found

// Status 404 Not Found

{
  "errors": [
    {
      "code": "1302",
      "detail": "Not found",
      "status": "404"
    }
  ]
}

422 Unprocessable Entity

// Status 422 Unprocessable Entity

{
  "errors": [
    {
      "code": "1303",
      "detail": "Invalid value for: Integration. Desc: Integration cannot be nil",
      "status": "422"
    }
  ]
}

429 Too Many Requests

// Status 429 Too Many Requests

{
  "errors": [
    {
      "code": "1300",
      "detail": "Too many requests",
      "status": "429"
    }
  ]
}

Delete OAuth Client

• DELETE /api/services/zis/connections/oauth/clients/{integration}/{client_uuid}

Deletes an OAuth client and all associated connections.

Parameters

Name	Type	In	Required	Description
client_uuid	string	Path	true	The UUID of the OAuth client
integration	string	Path	true	Name of the integration

Code Samples

cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/clients/{integration}/{client_uuid} \
-H "Authorization: Bearer {access_token}" \
-X DELETE

Go

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

func main() {
	url := "https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b"
	method := "DELETE"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b")
		.newBuilder();

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

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b',
  headers: {
	'Content-Type': 'application/json',
  },
};

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/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b"
headers = {
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/services/zis/connections/oauth/clients/my_integration/2fea765a-5ae4-4e3b-b457-a4f7836d041b")
request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")
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

401 Unauthorized

// Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1200",
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "1200",
      "detail": "Forbidden",
      "status": "403"
    }
  ]
}

404 Not Found

// Status 404 Not Found

{
  "errors": [
    {
      "code": "1302",
      "detail": "Not found",
      "status": "404"
    }
  ]
}

429 Too Many Requests

// Status 429 Too Many Requests

{
  "errors": [
    {
      "code": "1300",
      "detail": "Too many requests",
      "status": "429"
    }
  ]
}