Understanding connections

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 lets 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 within the hostname, such as zen*.com or my-*.zendesk.com.

You also can't use a wildcard with only a public domain suffix, such as *.com, *.com.au, or *.myshopify.com. For a list of public suffixes, see the public suffix list on publicsuffix.org.

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"
  }'