Configure Connectivity

Obtain connector keys

After the connector created, it will generate the following keys:

Identifier
OAUTH2 Redirect URL

Steps to get the keys value

Navigate to, Left panel --> More --> My Apps
Click the connector you want
In the Manage modal options, Click Connector Information
In the Connector Information modal, copy the required key value.

Where to use Identifier

When configuring an OAUTH2 Connector, The Identifier should be used under parameters [ ] --> redirect_uri.

Example: Obtain the Identifier (APP_XXXXXXXXX) and concatenate it to the redirect_uri value it as shown below

Code Snippet

{
  "name": "redirect_uri",
  "value": "?identifier=APP_XXXXXXXXX"
}

Where to use OAUTH2 Redirect URL

When registering an oauth2 App on 3rd-party website.

Example: User registered an App on Typeform website
Obtain the OAUTH2 Redirect URL and add it to Typeform App

Configure Connectivity

Setup basic, apikey and oauth2 connections.

Navigate to, Left panel --> More --> My Apps
Click the connector to be modified
In the Manage modal options, Click Configure Connectivity
Modify the fields and click Save

The JSON editor contains the following Arrays of Objects:

annotation
items
urls
parameters
headers
data
settings

annotation

Array of Objects. It contains one Object.

note_general - To add general notes or instructions when create/modify a connection. For example, the user need to know where to find the API Key from 3rd party App. This content will appear on top of the modal when creating a connection. Accept HTML formatting.

Code Snippet

[
  {
    "name": "note_general",
    "value": "YOUR_CUSTOM_CONNECTOR_NOTES"
  }
]

items

This array used for the following connection types
apikey
basic

component - Fixed value (ascx_connection_component_textbox), don't modify it.
id - Combination of two parts:
Part1: txt_connection_ : Technical name, don't modify it.
Part2: 3rd-party API Docs - key name, Example: API-Key
The id value will be txt_connection_API-Key

name - the key name used in the API Docs, Example: API-Key
placeholder - The text appears in the textbox when its empty. Its used as an helper about the kind of data to be added. Example: Authorisation Code...
required - Specify if this field is required. Possible values: true, false
subTitle - Text under title label. Used as a description of the textbox.
tabindex - The component order. in case the Connector has multiple components. Sorting in ascending order will depend on this value added on each component. Example: First component: tabindex=0, Second component: tabindex=1, Third component: tabindex=2
title - Component title. Example: username, password, Authorization code.
type - The component type. Possible values: text, password.
validationNote - Data validation note for this component.
isDisabled - Some Apps requires keys to be added with no value. Possible values: true, false
defaultValue - Specify if the component has a default value.

Connection type: apikey

The number of keys depending on App API Docs. Most Apps uses one key, each key need an Object from the code snippet below.

Code Snippet

[
    {
      "component": "ascx_connection_component_textbox",
      "id": "txt_connection_key",
      "name": "key",
      "placeholder": null,
      "required": "true",
      "subTitle": null,
      "tabindex": "0",
      "title": "Key",
      "type": "text",
      "validationNote": null,
      "isDisabled": null,
      "defaultValue": null
    }
]

Connection type: basic

Most Apps of security type basic uses username, password & Authorisation Code keys as shown in the code snippet below. This depend on the App API Docs.

Code Snippet

[
    {
      "component": "ascx_connection_component_textbox",
      "id": "txt_connection_username",
      "name": "username",
      "placeholder": "username...",
      "required": "optional",
      "subTitle": null,
      "tabindex": "0",
      "title": "Username",
      "type": "text",
      "validationNote": "validation note here!",
      "isDisabled": "false",
      "defaultValue": null
    },
    {
      "component": "ascx_connection_component_textbox",
      "id": "txt_connection_password",
      "name": "password",
      "placeholder": "password...",
      "required": "optional",
      "subTitle": null,
      "tabindex": "1",
      "title": "Password",
      "type": "password",
      "validationNote": null,
      "isDisabled": "false",
      "defaultValue": null
    },
    {
      "component": "ascx_connection_component_textbox",
      "id": "txt_connection_authorisationcode",
      "name": "Authorisation",
      "placeholder": "Authorisation Code...",
      "required": "true",
      "subTitle": null,
      "tabindex": "2",
      "title": "Authorisation Code",
      "type": "text",
      "validationNote": null,
      "isDisabled": "false",
      "defaultValue": null
    }
]

urls

Its an Array of Objects, each object should have 2 keys: name & value.

name - key name
value - key value

Example: An oauth2 app requires the following keys for the connection process:
authorisation
authentication
refresh_token

Code Snippet

[ 
    {
      "name": "authorisation",
      "value": "https://accounts.google.com/o/oauth2/v2/auth?scope={params.scope}&redirect_uri={params.redirect_uri}&response_type=code&client_id={params.client_id}&prompt=consent&access_type=offline"
    },
    {
      "name": "authentication",
      "value": "https://www.googleapis.com/oauth2/v4/token?code={query.code}&client_id={params.client_id}&client_secret={params.client_secret}&redirect_uri={params.redirect_uri}&grant_type={params.grant_type}"
    },
    {
      "name": "refresh_token",
      "value": "https://accounts.google.com/o/oauth2/token?client_id={params.client_id}&client_secret={params.client_secret}&refresh_token={query.refresh_token}&grant_type=refresh_token"
    }
]

parameters

It represent the request payload parameters (appending query parameters to the url). The parameters array used to organize the connection process configuration.
Its an Array of Objects, each object should have 2 keys: name & value.
Each key in parameters array belongs to the same key in the urls array.

Example:
Key name scope exists in urls array.
Key name scope exists in parameters array

Code Snippet

{
  "urls": [
    {
      "name": "authorisation",
      "value": "https://accounts.google.com/o/oauth2/v2/auth?scope={params.scope}"
    }
  ],
  "parameters": [
    {
      "name": "scope",
      "value": "https://www.googleapis.com/auth/drive"
    }
  ]
}

Example: An App requires the following keys for the connection process:
redirect_uri
response_type
client_id
client_secret
grant_type
scope
state

Code Snippet

[ 
    {
      "name": "redirect_uri",
      "value": "?identifier=YOUR_CUSTOM_APP_IDENTIFIER"
    },
    {
      "name": "response_type",
      "value": "YOUR_CUSTOM_APP_RESPONSE_TYPE"
    },
    {
      "name": "client_id",
      "value": "YOUR_CUSTOM_APP_CLIENT_SECRET"
    },
    {
      "name": "client_secret",
      "value": "YOUR_CUSTOM_APP_CLIENT_SECRET"
    },
    {
      "name": "grant_type",
      "value": "YOUR_CUSTOM_APP_GRANT_TYPE"
    },
    {
      "name": "scope",
      "value": "YOUR_CUSTOM_APP_SCOPES"
    },
    {
      "name": "state",
      "value": "YOUR_STATE_KEY_VALUE"
    }
]

headers

It represent the request payload headers. Its an Array of Objects, each object should have 2 keys: name & value.

Example: An App requires the following keys for the content type and connection process
Content-Type
Authorization

Code Snippet

[
    {
      "name": "Content-Type",
      "value": "application/x-www-form-urlencoded"
    },
    {
      "name": "Authorization",
      "value": "YOUR_CUSTOM_APP_AUTHORIZATION_KEY"
    }
]

data

It represents the request payload body. The data array used to organize the connection process configuration.
Its an Array of Objects, each object should have 3 keys: type, name & value.
Each key in data array belongs to the same key in the urls array.

type - belongs to the same key name that exists in the urls array
name - belongs to the same key value that exists in the urls array --> query parameters
value - key value

Example:
Key type authorisation in data array belong to the key name authorisation in the urls array.
Key name scope in the urls array will read its value from value in data array

Code Snippet

{
"urls": [
    {
      "name": "authorisation",
      "value": "https://accounts.google.com/o/oauth2/v2/auth?scope={params.scope}"
    }
],
"data": [
    {
      "type": "authorisation",
      "name": "scope",
      "value": "{params.scope}"
    }
],
"parameters": [
    {
      "name": "scope",
      "value": "https://www.googleapis.com/auth/drive"
    }
]
}

Example: An App requires the following data keys to be used in urls array:
authorisation
authentication
refresh_token

Code Snippet

[
    {
      "type": "authorisation",
      "name": "response_type",
      "value": "{params.response_type}"
    },
    {
      "type": "authorisation",
      "name": "client_id",
      "value": "{params.client_id}"
    },
    {
      "type": "authorisation",
      "name": "redirect_uri",
      "value": "{params.redirect_uri}"
    },
    {
      "type": "authorisation",
      "name": "scope",
      "value": "{params.scope}"
    },
    {
      "type": "authentication",
      "name": "grant_type",
      "value": "{params.grant_type}"
    },
    {
      "type": "refresh_token",
      "name": "grant_type",
      "value": "refresh_token"
    },
    {
      "type": "authentication",
      "name": "code",
      "value": "{query.code}"
    },
    {
      "type": "authentication",
      "name": "client_secret",
      "value": "{params.client_secret}"
    },
    {
      "type": "refresh_token",
      "name": "refresh_token",
      "value": "{connection.refresh_token}"
    }
  ]

settings

Some Apps requires special configuration to work. The settings array used for this case. Its an Array of Objects, each object should have 2 keys: name & value.
Example: The refresh_token of an App will expire after first use. The UPDATE_REFRESH_TOKEN_FROM_CONNECTION will be used and set its value to true (All keys/values will be available in the below table name Key-Value Guidance)

Code Snippet

[
  {
     "name": "UPDATE_REFRESH_TOKEN_FROM_CONNECTION",
     "value": "true, false"
  },
  {
     "name": "KEY_AUTHENTICATION_IDENTIFIER",
     "value": "identifier, state"
  },
  {
     "name": "SUPRESS_REFRESH_TOKEN",
     "value": "true, false"
  },
  {
     "name": "SUPRESS_TOKEN_BEARER",
     "value": "true"
  }
]

General Guidance

Variables	Possible Value	Notes
{params.value}	scope, redirect_uri, client_id, client_secret, grant_type, response_type, prompt	params → It represent the request payload parameters(appending query parameters to the url)
{header.value}		It represent the request payload headers
{connection.value}	refresh_token
{query.value}	code, refresh_token	query → it read from response url
{data.value}		It represents the request payload body

Key-Value Guidance

Variables	Possible Value	Notes
securityType	oauth2, basic, apikey
settings { }
settings.UPDATE_REFRESH_TOKEN_FROM_CONNECTION	true, false	some oauth2 application, for example, Xero, their refresh_token will expire after first use. In this case, the expected response of the refresh_token type endpoint will return a new “refresh_token” key. This new “refresh_token” key will replace the old refresh_token once used.
settings.KEY_AUTHENTICATION_IDENTIFIER	identifier, state	some oauth2 application, for example, Microsoft needs to use the state as an identifier because it does not allow to add query string parameters to the redirect_uri. If this value not existing then by default means identifier
settings.SUPRESS_REFRESH_TOKEN	true,false	some oauth2 application, for example, Slack their refresh_token does not exist, this key should be set to true. If this value not existing then the default means false
settings.ROOT_TOKEN_RESPONSE	Example: parent1, partent1.child1	The path of the response payload returned by the authentication call.
settings.SUPRESS_TOKEN_BEARER	true,false	if the word Bearer/bearer does not exist in the Authorization value, this key should be set to true. If this value not existing then the default means false
host{ }		some basic application, for example, Jira cloud, has a variable part in their URL
host.name		this key represents the name of the variable part in the URL
host.pattern		this key represents the URL including the variable part location

Updated on: 15/11/2022

Was this article helpful?

Thank you!