A connection stores credentials for a service or system, such as Slack, Shopify, or Zendesk. You can use a connection to authenticate REST API requests in a ZIS flow.

Connections are stored as resources in the ZIS Connections Service. You manage connections using the Connections API.

Connection types

Each connection has a type that corresponds to an authentication scheme or method. The Connections API endpoints used to create and manage a connection vary based on its type.

Connection type Connections API endpoints
API key API Key Connections endpoints
Basic authentication Basic Authentication Connections endpoints
Bearer token Bearer Token Connections endpoints
OAuth OAuth Clients and OAuth Connections endpoints. For usage instructions, see Creating and managing OAuth connections

To view all connections for an integration, use the Show Connections endpoint.

Creating a connection

To create an API key, basic authentication, or bearer token connection, use the corresponding create endpoint.

For example, the following Create Bearer Token Connection request creates a bearer token connection.

curl https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/connections/bearer_token \-H "Authorization: Bearer {access_token}" \-X POST \-H 'content-type: application/json' \-d '{  "name": "example_bearer_token",  "token": "MY_BEARER_TOKEN",  "allowed_domain": "api.example.com"  }'

To create an OAuth connection, you must use the OAuth Connections endpoints to complete an OAuth 2.0 flow between your ZIS integration and the system. The OAuth connection stores the resulting access token. For instructions, see Creating and managing OAuth connections.

Connection names

A connection's name must be unique within a ZIS integration. This applies across connection types. The connection name must be 3–64 characters, consisting only of uppercase or lowercase letters, numbers, _, and -.

Important: The "zendesk" connection name is reserved for OAuth connections to Zendesk.

Differences between bearer token and OAuth connections

Both bearer token and OAuth connections can store OAuth 2.0 access tokens. However, the types support different methods for obtaining and managing these tokens.

The following table describes some key differences between the connection types.

Difference Bearer token connection Oauth connection
Pre-existing access tokens Only stores pre-existing tokens Can't store pre-existing tokens. To store an access token, you must complete an OAuth flow between your ZIS integration and the system. The connection stores the resulting access token
Supported grant types Supports access tokens from any grant type Supports the authorization code and client credentials grant types. For OAuth connections created using an authoriziation code flow, the refresh token grant type is also supported
Token refreshes and renewals Only supports manual token refreshes and renewals Can automatically refresh or renew access tokens

Using a connection to authenticate API requests in a ZIS flow

A custom action lets you make REST API requests in a ZIS flow. When you define a custom action, you can specify a connection name in the connectionName property. ZIS uses this connection to authenticate requests for the action.

For example, the following custom action definition uses a connection named "zendesk".

"zendesk.get_tickets": {  "type": "ZIS::Action::Http",  "properties": {    "name": "zendesk.get_tickets",    "definition": {      "method": "GET",      "path": "/api/v2/tickets.json",      "connectionName": "zendesk"    }  }}

When the action makes a request, ZIS passes the connection's credentials in an HTTP header. ZIS determines the header based on the connection's type.

Connection type HTTP header
API key Set in the connection's header_name property.
See HTTP headers for API keys
Basic authentication Authorization Basic:
Bearer token Authorization Bearer:
OAuth Authorization Bearer:

HTTP headers for API keys

An API key connection requires an HTTP header name in the header_name property. When a custom action uses the connection to authenticate a request, ZIS passes the API key in this header.

For example, the following Create API Key Connection request sets the header_name as "x-api-key". When the connection is used to authenticate requests, ZIS passes the api_key value in the request's X-API-Key HTTP header.

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": "example_api_key",  "header_name": "x-api-key",  "api_key": "MY_API_KEY",  "allowed_domain": "api.example.com"  }'

Many APIs use a custom header to accept API keys. To get the appropriate header for an API request, consult the API's documentation.

Header requirements

An API key connection's header_name value can't exceed 128 characters. The value can only contain uppercase or lowercase letters, numbers, and the following characters: !, #, $, %, &, ', *, +, -, ., ^, _, `, |, and ~.

You can't use the following HTTP headers as header_name values:

  • accept
  • accept-charset
  • accept-encoding
  • accept-language
  • cache-control
  • connection
  • content-md5
  • cookie
  • date
  • expect
  • from
  • host
  • if-match
  • if-modified-since
  • if-none-match
  • if-range
  • if-unmodified-since
  • max-forwards
  • pragma
  • proxy-authenticate
  • proxy-authorization
  • range
  • server
  • referer
  • te
  • trailer
  • transfer-encoding
  • upgrade
  • user-agent
  • via
  • warning
  • www-authenticate
  • Headers starting with:
    • x-amz-
    • x-amzn-
    • x-forwarded-
    • x-zis

Allowed domain

An API key, basic authentication, or bearer token connection requires a hostname in the allowed_domain property. ZIS only passes the connection's credentials in requests to this hostname. Attempts to use the connection with other hostnames will fail. This helps prevent a ZIS integration from leaking credentials.

The following Create Basic Authentication Connection request creates a connection for the "api.example.com" hostname.

curl https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/connections/basic_auth \-H "Authorization: Bearer {access_token}" \-X POST \-H 'content-type: application/json' \-d '{  "name": "example_basic_auth_john",  "username": "[email protected]",  "password": "MY_PASSWORD",  "allowed_domain": "api.example.com"  }'

Allowed domain requirements

A connection's allowed_domain value can't exceed 253 characters. A subdomain in the value can't exceed 63 characters. The value must contain a valid domain name.

Don't specify a protocol or scheme in the allowed_domain value. ZIS always uses an https scheme. Other schemes are not supported.

Wildcards for allowed domain

The allowed_domain property supports an optional wildcard (*) subdomain. This let you use a connection with the bare domain and any subdomain.

To use a wildcard subdomain, the first two characters of the allowed_domain value must be *.. You can't use a wildcard in other parts of the hostname. For example, you can't use a wildcard with only a top-level domain, such as *.com or *.com.au, or within the hostname, such as zen*.com or my-*.zendesk.com.

The following Create Basic Authentication Connection request creates a connection that works with "example.com" and any subdomain of "example.com".

curl https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/connections/basic_auth \-H "Authorization: Bearer {access_token}" \-X POST \-H 'content-type: application/json' \-d '{  "name": "example_basic_auth_jane",  "username": "[email protected]",  "password": "MY_PASSWORD",  "allowed_domain": "*.example.com"  }'