Stores and manages API keys for an integration. See Understanding connections.

JSON format

API Key Connections are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
allowed_domain string false true Hostname the connection can be used on. See Allowed domain
api_key string false true API key. For security purposes, this value is redacted in responses
created_at string true false When the connection was created
header_name string false true Name of the HTTP header used to pass the API key in requests. See HTTP headers for API keys
name string false true Name used to uniquely identify the connection. See Connection names
updated_at string true false When the connection was last updated

Create API Key Connection

  • POST /api/services/zis/integrations/{integration}/connections/api_key

Creates an API key connection for the 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
integration string Path true Name of the integration

Example body

{  "allowed_domain": "api.example.com",  "api_key": "MY_API_KEY",  "header_name": "x-api-key",  "name": "my_api_key_connection"}

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/connections/api_key \-H "Authorization: Bearer {access_token}" \-X POST \-H 'content-type: application/json' \-d '{  "name": "my_api_key_connection",  "header_name": "x-api-key",  "api_key": "MY_API_KEY",  "allowed_domain": "api.example.com"  }'
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://support.zendesk.com/api/services/zis/integrations/my_integration/connections/api_key"	method := "POST"	payload := strings.NewReader(`{  "allowed_domain": "api.example.com",  "api_key": "MY_API_KEY",  "header_name": "x-api-key",  "name": "my_api_key_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/integrations/my_integration/connections/api_key")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"allowed_domain\": \"api.example.com\",  \"api_key\": \"MY_API_KEY\",  \"header_name\": \"x-api-key\",  \"name\": \"my_api_key_connection\"}""");
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({  "allowed_domain": "api.example.com",  "api_key": "MY_API_KEY",  "header_name": "x-api-key",  "name": "my_api_key_connection"});
var config = {  method: 'POST',  url: 'https://support.zendesk.com/api/services/zis/integrations/my_integration/connections/api_key',  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/integrations/my_integration/connections/api_key"
payload = json.loads("""{  "allowed_domain": "api.example.com",  "api_key": "MY_API_KEY",  "header_name": "x-api-key",  "name": "my_api_key_connection"}""")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/integrations/my_integration/connections/api_key")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.body = %q({  "allowed_domain": "api.example.com",  "api_key": "MY_API_KEY",  "header_name": "x-api-key",  "name": "my_api_key_connection"})response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

201 Created
// Status 201 Created
{  "api_key": {    "allowed_domain": "api.example.com",    "api_key": "*****",    "created_at": "1985-04-12T23:20:50.52Z",    "header_name": "x-api-key",    "name": "my_api_key_connection",    "updated_at": "1985-04-12T23:20:50.52Z"  }}
400 Bad Request
// Status 400 Bad Request
{  "errors": [    {      "code": "InvalidIntegration",      "title": "Specified integration is not valid"    }  ]}
401 Unauthorized
// Status 401 Unauthorized
{  "errors": [    {      "code": "InvalidCredentials",      "title": "Token length is invalid"    }  ]}
403 Forbidden
// Status 403 Forbidden
{  "errors": [    {      "code": "Forbidden",      "title": "Cannot access this resource. Missing scope write"    }  ]}
409 Conflict
// Status 409 Conflict
{  "errors": [    {      "code": "Conflict",      "title": "Resource conflict"    }  ]}
429 Too Many Requests
// Status 429 Too Many Requests
{  "errors": [    {      "code": "TooManyRequests",      "title": "Too many requests"    }  ]}

Show API Key Connection

  • GET /api/services/zis/integrations/{integration}/connections/api_key/{name}

Returns the details of an API key connection.

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
name string Path true Name of the API key connection

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/connections/api_key/{name} \-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/api_key/my_api_key_connection"	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/api_key/my_api_key_connection")		.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/integrations/my_integration/connections/api_key/my_api_key_connection',  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/integrations/my_integration/connections/api_key/my_api_key_connection"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/api_key/my_api_key_connection")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
{  "api_key": {    "allowed_domain": "api.example.com",    "api_key": "*****",    "created_at": "1985-04-12T23:20:50.52Z",    "header_name": "x-api-key",    "name": "my_api_key_connection",    "updated_at": "1985-04-12T23:20:50.52Z"  }}
401 Unauthorized
// Status 401 Unauthorized
{  "errors": [    {      "code": "InvalidCredentials",      "title": "Token length is invalid"    }  ]}
403 Forbidden
// Status 403 Forbidden
{  "errors": [    {      "code": "Forbidden",      "title": "Cannot access this resource. Missing scope write"    }  ]}
404 Not Found
// Status 404 Not Found
{  "errors": [    {      "code": "NotFound",      "title": "Connection does not exist"    }  ]}
429 Too Many Requests
// Status 429 Too Many Requests
{  "errors": [    {      "code": "TooManyRequests",      "title": "Too many requests"    }  ]}

Update API Key Connection

  • PATCH /api/services/zis/integrations/{integration}/connections/api_key/{name}

Updates an API key connection.

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
name string Path true Name of the API key connection

Example body

{  "api_key": "MY_API_KEY",  "header_name": "x-api-key"}

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/connections/api_key/{name} \-H "Authorization: Bearer {access_token}" \-X PATCH \-H 'content-type: application/json' \-d '{  "header_name": "x-api-key",  "api_key": "MY_API_KEY"  }'
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://support.zendesk.com/api/services/zis/integrations/my_integration/connections/api_key/my_api_key_connection"	method := "PATCH"	payload := strings.NewReader(`{  "api_key": "MY_API_KEY",  "header_name": "x-api-key"}`)	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/integrations/my_integration/connections/api_key/my_api_key_connection")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"api_key\": \"MY_API_KEY\",  \"header_name\": \"x-api-key\"}""");
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({  "api_key": "MY_API_KEY",  "header_name": "x-api-key"});
var config = {  method: 'PATCH',  url: 'https://support.zendesk.com/api/services/zis/integrations/my_integration/connections/api_key/my_api_key_connection',  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/integrations/my_integration/connections/api_key/my_api_key_connection"
payload = json.loads("""{  "api_key": "MY_API_KEY",  "header_name": "x-api-key"}""")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/integrations/my_integration/connections/api_key/my_api_key_connection")request = Net::HTTP::Patch.new(uri, "Content-Type": "application/json")request.body = %q({  "api_key": "MY_API_KEY",  "header_name": "x-api-key"})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
400 Bad Request
// Status 400 Bad Request
{  "errors": [    {      "code": "InvalidIntegration",      "title": "Specified integration is not valid"    }  ]}
401 Unauthorized
// Status 401 Unauthorized
{  "errors": [    {      "code": "InvalidCredentials",      "title": "Token length is invalid"    }  ]}
403 Forbidden
// Status 403 Forbidden
{  "errors": [    {      "code": "Forbidden",      "title": "Cannot access this resource. Missing scope write"    }  ]}
404 Not Found
// Status 404 Not Found
{  "errors": [    {      "code": "NotFound",      "title": "Connection does not exist"    }  ]}
429 Too Many Requests
// Status 429 Too Many Requests
{  "errors": [    {      "code": "TooManyRequests",      "title": "Too many requests"    }  ]}

Delete API Key Connection

  • DELETE /api/services/zis/integrations/{integration}/connections/api_key/{name}

Deletes an API key connection.

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
name string Path true Name of the API key connection

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/connections/api_key/{name} \-H "Authorization: Bearer {access_token}" \-X DELETE
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/services/zis/integrations/my_integration/connections/api_key/my_api_key_connection"	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/integrations/my_integration/connections/api_key/my_api_key_connection")		.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/integrations/my_integration/connections/api_key/my_api_key_connection',  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/integrations/my_integration/connections/api_key/my_api_key_connection"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/integrations/my_integration/connections/api_key/my_api_key_connection")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": "InvalidCredentials",      "title": "Token length is invalid"    }  ]}
403 Forbidden
// Status 403 Forbidden
{  "errors": [    {      "code": "Forbidden",      "title": "Cannot access this resource. Missing scope write"    }  ]}
404 Not Found
// Status 404 Not Found
{  "errors": [    {      "code": "NotFound",      "title": "Connection does not exist"    }  ]}
429 Too Many Requests
// Status 429 Too Many Requests
{  "errors": [    {      "code": "TooManyRequests",      "title": "Too many requests"    }  ]}