Stores and manages OAuth access tokens for an integration. See Creating and managing OAuth connections.

JSON format

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

NameTypeRead-onlyMandatoryDescription
access_tokenstringtruefalseThe OAuth access token
created_bystringtruefalseUser who created the connection
integrationstringfalsefalseThe name of the integration
namestringfalsefalseName used to uniquely identify the connection. See Connection names
oauth_access_token_response_bodystringtruefalseThe response from the OAuth provider when getting an access token
oauth_client_uuidstringfalsefalseOAuth client UUID is a globally unique identifier for an OAuth client
oauth_url_subdomainstringfalsefalseSubdomain is used to interpolate the subdomain placeholder in the OAuth provider's authorization or token URL
permission_scopestringfalsefalseThe space delimited string to list the desired OAuth permissions for the OAuth flow
refresh_tokenstringtruefalseThe OAuth refresh token
token_expirystringtruefalseThe expiry date time of the access token. Format of YYYY-MM-DDThh:mm:ssZ
token_typestringtruefalseThe type of token. For example, "bearer"
uuidstringtruefalseThe UUID of the connection
zendesk_account_idintegertruefalseThe Zendesk account ID

Start OAuth Flow

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

Starts the OAuth flow for the client.

Authentication

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

Parameters

NameTypeInRequiredDescription
integrationstringPathtrueName of the integration

Example body

{  "allow_offline_access": true,  "grant_type": "authorization_code",  "name": "my_connection_name",  "oauth_client_name": "my_oauth_client_name",  "oauth_client_uuid": "9c81f444-4beb-4ba7-9bcc-6b2d068e7ade",  "oauth_url_subdomain": "foobar",  "origin_oauth_redirect_url": "https://client.int/callback",  "permission_scopes": "read write"}

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/start/{integration} \-H "Authorization: Bearer {access_token}" \-X POST \-H 'content-type: application/json' \-d '{  "allow_offline_access": true,  "grant_type": "authorization_code",  "name": "my_connection_name",  "oauth_client_name": "my_oauth_client_name",  "oauth_client_uuid": "9c81f444-4beb-4ba7-9bcc-6b2d068e7ade",  "oauth_url_subdomain": "foobar",  "origin_oauth_redirect_url": "https://client.int/callback",  "permission_scopes": "read write"}'
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://support.zendesk.com/api/services/zis/connections/oauth/start/my_integration"	method := "POST"	payload := strings.NewReader(`{  "allow_offline_access": true,  "grant_type": "authorization_code",  "name": "my_connection_name",  "oauth_client_name": "my_oauth_client_name",  "oauth_client_uuid": "9c81f444-4beb-4ba7-9bcc-6b2d068e7ade",  "oauth_url_subdomain": "foobar",  "origin_oauth_redirect_url": "https://client.int/callback",  "permission_scopes": "read write"}`)	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/start/my_integration")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"allow_offline_access\": true,  \"grant_type\": \"authorization_code\",  \"name\": \"my_connection_name\",  \"oauth_client_name\": \"my_oauth_client_name\",  \"oauth_client_uuid\": \"9c81f444-4beb-4ba7-9bcc-6b2d068e7ade\",  \"oauth_url_subdomain\": \"foobar\",  \"origin_oauth_redirect_url\": \"https://client.int/callback\",  \"permission_scopes\": \"read write\"}""");
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({  "allow_offline_access": true,  "grant_type": "authorization_code",  "name": "my_connection_name",  "oauth_client_name": "my_oauth_client_name",  "oauth_client_uuid": "9c81f444-4beb-4ba7-9bcc-6b2d068e7ade",  "oauth_url_subdomain": "foobar",  "origin_oauth_redirect_url": "https://client.int/callback",  "permission_scopes": "read write"});
var config = {  method: 'POST',  url: 'https://support.zendesk.com/api/services/zis/connections/oauth/start/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 requestsimport json
url = "https://support.zendesk.com/api/services/zis/connections/oauth/start/my_integration"
payload = json.loads("""{  "allow_offline_access": true,  "grant_type": "authorization_code",  "name": "my_connection_name",  "oauth_client_name": "my_oauth_client_name",  "oauth_client_uuid": "9c81f444-4beb-4ba7-9bcc-6b2d068e7ade",  "oauth_url_subdomain": "foobar",  "origin_oauth_redirect_url": "https://client.int/callback",  "permission_scopes": "read write"}""")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/start/my_integration")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.body = %q({  "allow_offline_access": true,  "grant_type": "authorization_code",  "name": "my_connection_name",  "oauth_client_name": "my_oauth_client_name",  "oauth_client_uuid": "9c81f444-4beb-4ba7-9bcc-6b2d068e7ade",  "oauth_url_subdomain": "foobar",  "origin_oauth_redirect_url": "https://client.int/callback",  "permission_scopes": "read write"})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
{  "redirect_url": "https://foobar.zendesk.com/api/services/zis/connections/oauth/start_redirect?flow_token=xyz"}
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"    }  ]}

Start OAuth Redirect

  • GET /api/services/zis/connections/oauth/start_redirect?flow_token={flow_token}

When making an HTTPs request to Start OAuth Flow, this endpoint is returned in redirect_url in the response.

Parameters

NameTypeInRequiredDescription
flow_tokenstringQuerytrueThe token that is part of the redirect_url response from the /oauth/start/{integration} endpoint

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/start_redirect?flow_token={flow_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/services/zis/connections/oauth/start_redirect?flow_token=TgtEfGWfduqzwNnkST8jNsr5MnjPnYEt"	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/start_redirect")		.newBuilder()		.addQueryParameter("flow_token", "TgtEfGWfduqzwNnkST8jNsr5MnjPnYEt");
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/start_redirect',  headers: {	'Content-Type': 'application/json',  },  params: {    'flow_token': 'TgtEfGWfduqzwNnkST8jNsr5MnjPnYEt',  },};
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/start_redirect?flow_token=TgtEfGWfduqzwNnkST8jNsr5MnjPnYEt"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/start_redirect")uri.query = URI.encode_www_form("flow_token": "TgtEfGWfduqzwNnkST8jNsr5MnjPnYEt")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)

307 Temporary Redirect
// Status 307 Temporary Redirect
null
400 Bad Request
// Status 400 Bad Request
{  "errors": [    {      "code": "1301",      "detail": "Invalid request",      "status": "400"    }  ]}

OAuth Token

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

Returns a proxy for the Zendesk OAuth Token URL. For more information on the Zendesk OAuth flow, see Using OAuth authentication with your application.

Parameters

NameTypeInRequiredDescription
integrationstringPathtrueName of the integration

Example body

{  "client_id": "my_client_id",  "client_secret": "my_client_secret",  "code": "LgwEzL8CA3aRA35r5QYfRbjjMa3Iacsk1CvwcRsnM",  "grant_type": "authorization_code",  "redirect_uri": "https://client.int/callback",  "scope": "read write"}

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/tokens/{integration} \-X POST \-H 'content-type: application/json' \-d '{  "client_id": "my_client_id",  "client_secret": "my_client_secret",  "code": "LgwEzL8CA3aRA35r5QYfRbjjMa3Iacsk1CvwcRsnM",  "grant_type": "authorization_code",  "redirect_uri": "https://client.int/callback",  "scope": "read write"}'
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://support.zendesk.com/api/services/zis/connections/oauth/tokens/my_integration"	method := "POST"	payload := strings.NewReader(`{  "client_id": "my_client_id",  "client_secret": "my_client_secret",  "code": "LgwEzL8CA3aRA35r5QYfRbjjMa3Iacsk1CvwcRsnM",  "grant_type": "authorization_code",  "redirect_uri": "https://client.int/callback",  "scope": "read write"}`)	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/tokens/my_integration")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"client_id\": \"my_client_id\",  \"client_secret\": \"my_client_secret\",  \"code\": \"LgwEzL8CA3aRA35r5QYfRbjjMa3Iacsk1CvwcRsnM\",  \"grant_type\": \"authorization_code\",  \"redirect_uri\": \"https://client.int/callback\",  \"scope\": \"read write\"}""");
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({  "client_id": "my_client_id",  "client_secret": "my_client_secret",  "code": "LgwEzL8CA3aRA35r5QYfRbjjMa3Iacsk1CvwcRsnM",  "grant_type": "authorization_code",  "redirect_uri": "https://client.int/callback",  "scope": "read write"});
var config = {  method: 'POST',  url: 'https://support.zendesk.com/api/services/zis/connections/oauth/tokens/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 requestsimport json
url = "https://support.zendesk.com/api/services/zis/connections/oauth/tokens/my_integration"
payload = json.loads("""{  "client_id": "my_client_id",  "client_secret": "my_client_secret",  "code": "LgwEzL8CA3aRA35r5QYfRbjjMa3Iacsk1CvwcRsnM",  "grant_type": "authorization_code",  "redirect_uri": "https://client.int/callback",  "scope": "read write"}""")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/tokens/my_integration")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.body = %q({  "client_id": "my_client_id",  "client_secret": "my_client_secret",  "code": "LgwEzL8CA3aRA35r5QYfRbjjMa3Iacsk1CvwcRsnM",  "grant_type": "authorization_code",  "redirect_uri": "https://client.int/callback",  "scope": "read write"})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
{  "access_token": "ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC-ThYWDqY2_M5w==",  "scope": "read write",  "token_type": "bearer"}
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"    }  ]}

Exchange Verification Code

  • GET /api/services/zis/connections/oauth/access_codes/{integration}?verification_code={verification_code}

Returns an access code and connection UUID when the verification code is provided.

Authentication

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

Parameters

NameTypeInRequiredDescription
verification_codestringQuerytrueThe verification code returned from the authorization flow
integrationstringPathtrueName of the integration

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/access_codes/{integration}?verification_code={verification_code} \-H "Authorization: Bearer {access_token}"
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/services/zis/connections/oauth/access_codes/my_integration?verification_code=s8fOrC4oP"	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/access_codes/my_integration")		.newBuilder()		.addQueryParameter("verification_code", "s8fOrC4oP");
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/access_codes/my_integration',  headers: {	'Content-Type': 'application/json',  },  params: {    'verification_code': 's8fOrC4oP',  },};
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/access_codes/my_integration?verification_code=s8fOrC4oP"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/access_codes/my_integration")uri.query = URI.encode_www_form("verification_code": "s8fOrC4oP")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
{  "access_token": "ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC-ThYWDqY2_M5w==",  "created_by": "test_user",  "integration": "my_integration",  "oauth_access_token_response_body": "{\"access_token\":\"ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC\"}",  "origin_oauth_redirect_url": "https://client.int/callback",  "permission_scope": "read write",  "raw_callback_params": "code=aPrx.f3G28C1ueiVxd.Skd2w.u5bioOnuzTNDdT81IaImk7PKmXXHAfVBtYu5rK.Yh.lDL4jsA&state=CC5j68_SRVA5pSBbDkMq2sa4d36NyibXf12_Hf2POkk",  "refresh_token": "cs95Xaw_F5PKcxO4fQ9bZKklHKncdkXIc9qGrvktPt2elg==",  "token_expiry": "2021-10-01T12:44:22Z",  "token_type": "bearer",  "uuid": "ac10a230-0c43-45f8-b221-9e085ce90418",  "zendesk_account_id": 123456}
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"    }  ]}

Refresh OAuth Token

  • GET /api/services/zis/connections/refresh/{integration}

Refreshes an OAuth token.

Parameters

NameTypeInRequiredDescription
namestringQueryfalseName of connection. Specify either "uuid" or "name"
uuidstringQueryfalseUUID of connection. Specify either "uuid" or "name"
integrationstringPathtrueName of the integration

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/services/zis/connections/refresh/{integration}?uuid={uuid} \-H "Authorization: Bearer {access_token}"
cURL
curl https://{subdomain}.zendesk.com/api/services/zis/connections/refresh/{integration}?name={name} \-H "Authorization: Bearer {access_token}"
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/services/zis/connections/refresh/my_integration?name=my_oauth_connection&uuid=9c865cd6-858e-42c6-b14d-2cc43f3b4ac4"	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/refresh/my_integration")		.newBuilder()		.addQueryParameter("name", "my_oauth_connection")		.addQueryParameter("uuid", "9c865cd6-858e-42c6-b14d-2cc43f3b4ac4");
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/refresh/my_integration',  headers: {	'Content-Type': 'application/json',  },  params: {    'name': 'my_oauth_connection',    'uuid': '9c865cd6-858e-42c6-b14d-2cc43f3b4ac4',  },};
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/refresh/my_integration?name=my_oauth_connection&uuid=9c865cd6-858e-42c6-b14d-2cc43f3b4ac4"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/refresh/my_integration")uri.query = URI.encode_www_form("name": "my_oauth_connection", "uuid": "9c865cd6-858e-42c6-b14d-2cc43f3b4ac4")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
{  "access_token": "ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC-ThYWDqY2_M5w==",  "created_by": "test_user",  "integration": "my_integration",  "name": "my_oauth_connection",  "oauth_access_token_response_body": "{\"access_token\":\"ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC\"}",  "oauth_client_uuid": "9c81f444-4beb-4ba7-9bcc-6b2d068e7ade",  "oauth_url_subdomain": "foobar",  "permission_scope": "read write",  "refresh_token": "cs95Xaw_F5PKcxO4fQ9bZKklHKncdkXIc9qGrvktPt2elg==",  "token_expiry": "2021-10-01T12:44:22Z",  "token_type": "bearer",  "uuid": "ac10a230-0c43-45f8-b221-9e085ce90418",  "zendesk_account_id": 123456}
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"    }  ]}

Show OAuth Connection

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

Returns connection details for an integration.

Authentication

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

Parameters

NameTypeInRequiredDescription
namestringQueryfalseName of connection. Specify either "uuid" or "name"
uuidstringQueryfalseUUID of connection. Specify either "uuid" or "name"
integrationstringPathtrueName of the integration

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/services/zis/connections/{integration}?uuid={uuid} \-H "Authorization: Bearer {access_token}"
cURL
curl https://{subdomain}.zendesk.com/api/services/zis/connections/{integration}?name={name} \-H "Authorization: Bearer {access_token}"
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/services/zis/connections/my_integration?name=my_oauth_connection&uuid=9c865cd6-858e-42c6-b14d-2cc43f3b4ac4"	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/my_integration")		.newBuilder()		.addQueryParameter("name", "my_oauth_connection")		.addQueryParameter("uuid", "9c865cd6-858e-42c6-b14d-2cc43f3b4ac4");
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/my_integration',  headers: {	'Content-Type': 'application/json',  },  params: {    'name': 'my_oauth_connection',    'uuid': '9c865cd6-858e-42c6-b14d-2cc43f3b4ac4',  },};
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/my_integration?name=my_oauth_connection&uuid=9c865cd6-858e-42c6-b14d-2cc43f3b4ac4"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/my_integration")uri.query = URI.encode_www_form("name": "my_oauth_connection", "uuid": "9c865cd6-858e-42c6-b14d-2cc43f3b4ac4")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
{  "access_token": "ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC-ThYWDqY2_M5w==",  "created_by": "test_user",  "integration": "my_integration",  "name": "my_oauth_connection",  "oauth_access_token_response_body": "{\"access_token\":\"ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC\"}",  "oauth_client_uuid": "9c81f444-4beb-4ba7-9bcc-6b2d068e7ade",  "oauth_url_subdomain": "foobar",  "permission_scope": "read write",  "refresh_token": "cs95Xaw_F5PKcxO4fQ9bZKklHKncdkXIc9qGrvktPt2elg==",  "token_expiry": "2021-10-01T12:44:22Z",  "token_type": "bearer",  "uuid": "ac10a230-0c43-45f8-b221-9e085ce90418",  "zendesk_account_id": 123456}
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"    }  ]}

Show OAuth Connections

  • GET /api/services/zis/integrations/{integration}/connections?named={named}

Returns a list of Connections for the integration. The support is now limited to ?named=true to return only the named connections.

Authentication

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

Parameters

NameTypeInRequiredDescription
namedbooleanQuerytrueBoolean to return named connections only
integrationstringPathtrueName of the integration

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/connections?named=true \-H "Authorization: Bearer {access_token}"
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/services/zis/integrations/my_integration/connections?named=true"	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/integrations/my_integration/connections")		.newBuilder()		.addQueryParameter("named", "true");
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/integrations/my_integration/connections',  headers: {	'Content-Type': 'application/json',  },  params: {    'named': 'true',  },};
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/integrations/my_integration/connections?named=true"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/integrations/my_integration/connections")uri.query = URI.encode_www_form("named": "true")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
{  "connections": [    {      "access_token": "ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC-ThYWDqY2_M5w==",      "created_by": "test_user",      "integration": "my_integration",      "name": "my_oauth_connection",      "oauth_access_token_response_body": "{\"access_token\":\"ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC\"}",      "oauth_client_uuid": "9c81f444-4beb-4ba7-9bcc-6b2d068e7ade",      "oauth_url_subdomain": "foobar",      "permission_scope": "read write",      "refresh_token": "cs95Xaw_F5PKcxO4fQ9bZKklHKncdkXIc9qGrvktPt2elg==",      "token_expiry": "2021-10-01T12:44:22Z",      "token_type": "bearer",      "uuid": "ac10a230-0c43-45f8-b221-9e085ce90418",      "zendesk_account_id": 123456    }  ]}
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"    }  ]}

Update Connection

  • PATCH /api/services/zis/connections/{integration}?uuid={uuid}

Updates connection details.

Parameters

NameTypeInRequiredDescription
uuidstringQuerytrueUUID of the connection
integrationstringPathtrueName of the integration

Example body

{  "name": "my_oauth_connection"}

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/services/zis/connections/{integration}?uuid={uuid} \-H "Authorization: Bearer {access_token}" \-X PATCH \-H 'content-type: application/json' \-d '{  "name": "my_oauth_connection"}'
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://support.zendesk.com/api/services/zis/connections/my_integration?uuid=9c865cd6-858e-42c6-b14d-2cc43f3b4ac4"	method := "PATCH"	payload := strings.NewReader(`{  "name": "my_oauth_connection"}`)	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/my_integration")		.newBuilder()		.addQueryParameter("uuid", "9c865cd6-858e-42c6-b14d-2cc43f3b4ac4");RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"name\": \"my_oauth_connection\"}""");
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({  "name": "my_oauth_connection"});
var config = {  method: 'PATCH',  url: 'https://support.zendesk.com/api/services/zis/connections/my_integration',  headers: {	'Content-Type': 'application/json',  },  params: {    'uuid': '9c865cd6-858e-42c6-b14d-2cc43f3b4ac4',  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport json
url = "https://support.zendesk.com/api/services/zis/connections/my_integration?uuid=9c865cd6-858e-42c6-b14d-2cc43f3b4ac4"
payload = json.loads("""{  "name": "my_oauth_connection"}""")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/my_integration")uri.query = URI.encode_www_form("uuid": "9c865cd6-858e-42c6-b14d-2cc43f3b4ac4")request = Net::HTTP::Patch.new(uri, "Content-Type": "application/json")request.body = %q({  "name": "my_oauth_connection"})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"    }  ]}
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 Connection

  • DELETE /api/services/zis/connections/{integration}

Deletes the authorization token stored in the ZIS Connection Service.

Parameters

NameTypeInRequiredDescription
namestringQueryfalseName of connection. Specify either "uuid" or "name"
uuidstringQueryfalseUUID of connection. Specify either "uuid" or "name"
integrationstringPathtrueName of the integration

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/services/zis/connections/{integration}?uuid={uuid} \-H "Authorization: Bearer {access_token}" \-X DELETE
cURL
curl curl https://{subdomain}.zendesk.com/api/services/zis/connections/{integration}?name={name} \-H "Authorization: Bearer {access_token}" \-X DELETE
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/services/zis/connections/my_integration?name=my_oauth_connection&uuid=9c865cd6-858e-42c6-b14d-2cc43f3b4ac4"	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/my_integration")		.newBuilder()		.addQueryParameter("name", "my_oauth_connection")		.addQueryParameter("uuid", "9c865cd6-858e-42c6-b14d-2cc43f3b4ac4");
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/my_integration',  headers: {	'Content-Type': 'application/json',  },  params: {    'name': 'my_oauth_connection',    'uuid': '9c865cd6-858e-42c6-b14d-2cc43f3b4ac4',  },};
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/my_integration?name=my_oauth_connection&uuid=9c865cd6-858e-42c6-b14d-2cc43f3b4ac4"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/my_integration")uri.query = URI.encode_www_form("name": "my_oauth_connection", "uuid": "9c865cd6-858e-42c6-b14d-2cc43f3b4ac4")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"    }  ]}