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
Thank you!