A connection lets you safely store API credentials for a service or system, such as Slack or Shopify. You can use a connection to authenticate REST API calls in the bot builder's Make API call step. You must be an admin to create connections.
A connection supports one of the following API authentication methods:
- API key
- Basic authentication
- Bearer token
- OAuth 2.0
This authentication method determines the type of credentials the connection stores. For example, a basic authentication connection stores a username and password. After you create a connection, you can't change its authentication type.
Different APIs support different authentication methods. To determine the appropriate authentication method for an API call, consult the API's documentation.
HTTP headers for authentication types
|Authentication type||HTTP header|
|API key||Set when you create the connection. See HTTP headers for API keys|
|OAuth 2.0||Access token is sent to the service in
For more information about using a connection in a bot, see Using the Make API call step in the bot builder.
Creating an OAuth client
An OAuth connection stores an OAuth 2.0 access token for a service or system, such as Slack, Shopify, or Zendesk.
Before creating a connection with the OAuth 2.0 authentication type, you must configure an OAuth client. When configuring the OAuth client, you need the client ID, client secret, authorization URL, token URL, and scopes from the external system's OAuth configuration interface or admin portal. These credentials are generated while registering your client application (such as Zendesk) with the external system. The exact steps vary based on the external service. If required, set the client's callback URL as "https://zis.zendesk.com/api/services/zis/connections/oauth/callback".
- Authorization code
- Client credentials
The refresh token grant type is supported for OAuth 2.0 clients created using an authorization code grant type. If the system's access token response includes non-empty
refresh_token values, the access token is automatically refreshed using the refresh token.
OAuth 2.0 connections created with a client using the Clients credentials grant type may include a token expiry value. In these cases, when the token expires, a new access token is fetched using the same OAuth client.
To create an OAuth client
- In Admin Center, click Apps and integrations in the sidebar, then select Connections > OAuth Clients.
- Enter a name for the client. You cannot change this name after you create the client.
- Enter the Client ID. This is a unique identifier assigned to your OAuth client, similar to a username for your client.
- Enter the Client secret. This acts as a password for your client application and establishes trust between Zendesk and the external system.
- (Authorization code grant type only) Enter the Authorization URL. This is the server URL used to receive an authorization code.
- Enter the Token URL. This is the URL used to receive an access token.
- Enter a space-separate list of default scopes. Scopes are permissions that represent what a client application can access on behalf of the user.
- Click Save to create the client.
Creating a connection
You can create a connection in Admin Center from the Connections page.
To create a connection
- In Admin Center, click Apps and integrations in the sidebar, then select Connections > Connections.
- Click Create connection.
- Select an authentication type.
- Enter a name for the connection. You can't change this name after you create the connection.
- Do one of the following:
- (API Key, Basic authentication, Bearer token) Configure the connection's authentication credentials. The connection uses these details to authenticate REST API calls to the service or system.
- (OAuth 2.0) Select the client to use and optionally enter a space-separated list of scopes. If you do not enter any scopes, the default ones specified in the OAuth client are used.
- Enter an allowed domain for the connection. You can't change the allowed domain after you create the connection. For more information, see Allowed domain.
- Click Save to create the connection.
After you've created the connection, you can view its details from the Connections page in Admin Center. See Managing connections.
Each connection requires a URL hostname as an allowed domain. Zendesk only passes the connection's credentials in API calls to this hostname. Attempts to use the connection with other hostnames will fail. This helps prevent an accidental leak of the connection's credentials. After you create a connection, you can't change its allowed domain.
For example, you can only use a connection with an allowed domain of "api.example.com" to make API calls to the “https://api.example.com” hostname.
Allowed domain requirements
A connection's allowed domain can't exceed 128 characters. A subdomain or domain in the value can't exceed 63 characters. The value must contain a valid domain name.
A connection always uses an
https scheme. Other schemes, such as
ftps, are not supported.
Wildcards for allowed domain
A connection's allowed domain supports an optional wildcard (*) subdomain. This lets you use the connection with the bare domain and any subdomain. For example, you can use a connection with an allowed domain of
*.example.com to authenticate API calls to "example.com" or any subdomain of "example.com".
To use a wildcard subdomain, the first two characters of the allowed domain must be
*.. You can't use a wildcard in other parts of the hostname. For example, you can't use a wildcard within a hostname, such as
HTTP headers for API keys
When you create an API key connection, you must specify an HTTP header name. When the connection is used to make an API call, Zendesk passes the API key as the value for this header.
Many APIs use a custom header to accept API keys. To get the appropriate header name for an API call, consult the API's documentation.
Header name requirements
An API key connection's header name can't exceed 128 characters. The header name can only contain letters, hyphens (
-), and underscores (
- Header names starting with: