OAuth Connections
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:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
access_token | string | true | false | The OAuth access token |
created_by | string | true | false | User who created the connection |
integration | string | false | false | The name of the integration |
name | string | false | false | Name used to uniquely identify the connection. See Connection names |
oauth_access_token_response_body | string | true | false | The response from the OAuth provider when getting an access token |
oauth_client_uuid | string | false | false | OAuth client UUID is a globally unique identifier for an OAuth client |
oauth_url_subdomain | string | false | false | Subdomain is used to interpolate the subdomain placeholder in the OAuth provider's authorization or token URL |
permission_scope | string | false | false | The space delimited string to list the desired OAuth permissions for the OAuth flow |
refresh_token | string | true | false | The OAuth refresh token |
token_expiry | string | true | false | The expiry date time of the access token. Format of YYYY-MM-DDThh:mm:ssZ |
token_type | string | true | false | The type of token. For example, "bearer" |
uuid | string | true | false | The UUID of the connection |
zendesk_account_id | integer | true | false | The 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
Name | Type | In | Required | Description |
---|---|---|---|---|
integration | string | Path | true | Name 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 requests
import 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
Name | Type | In | Required | Description |
---|---|---|---|---|
flow_token | string | Query | true | The 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
Name | Type | In | Required | Description |
---|---|---|---|---|
integration | string | Path | true | Name 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 requests
import 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
Name | Type | In | Required | Description |
---|---|---|---|---|
verification_code | string | Query | true | The verification code returned from the authorization flow |
integration | string | Path | true | Name 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
Name | Type | In | Required | Description |
---|---|---|---|---|
name | string | Query | false | Name of connection. Specify either "uuid" or "name" |
uuid | string | Query | false | UUID of connection. Specify either "uuid" or "name" |
integration | string | Path | true | Name 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
Name | Type | In | Required | Description |
---|---|---|---|---|
name | string | Query | false | Name of connection. Specify either "uuid" or "name" |
uuid | string | Query | false | UUID of connection. Specify either "uuid" or "name" |
integration | string | Path | true | Name 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
Name | Type | In | Required | Description |
---|---|---|---|---|
named | boolean | Query | true | Boolean to return named connections only |
integration | string | Path | true | Name 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
Name | Type | In | Required | Description |
---|---|---|---|---|
uuid | string | Query | true | UUID of the connection |
integration | string | Path | true | Name 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 requests
import 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
Name | Type | In | Required | Description |
---|---|---|---|---|
name | string | Query | false | Name of connection. Specify either "uuid" or "name" |
uuid | string | Query | false | UUID of connection. Specify either "uuid" or "name" |
integration | string | Path | true | Name 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"
}
]
}