What are Connector Settings?

Connector settings determine:

How a connector appears to your tenants
How you and your tenants authenticate to the connector
The underling taps and targets that your connector uses

Example Connector Settings

    {
        "id": "shopify",
        "label": "Shopify",
        "type": "api",
        "tags": [
            "ecommerce",
            "featured"
        ],
        "icon": "https://s3.amazonaws.com/cdn.hotglue.xyz/images/logos/shopify.svg",
        "domain": "shopify.com",
        "isConnector": true,
        "isSource": false,
        "isTarget": false,
        "read_connector": {
            "id": "shopify"
        },
        "write_connector": {
            "id": "shopify-v2",
            "install_uri": "git+https://gitlab.com/hotglue/target-shopify-v2.git@bump-to-use-new-target-sdk"
        },
        "connect_ui_params": {
            "api_key": {
                "label": "API Password",
                "description": "Shopify API Password",
                "type": "password"
            },
            "api_key_id": {
                "label": "API Key",
                "description": "Shopify API Key",
                "type": "password",
                "required": false
            },
            "shop": {
                "label": "Shop",
                "description": "Shopify shop name (ie. the value test_shop in the string https://test_shop.myshopify.com)",
                "adornment": {
                    "start": "https://",
                    "end": ".myshopify.com"
                }
            },
            "bulk": {
                "type": "boolean",
                "label": "Bulk",
                "required": false
            }
        },
        "options": {
            "auto_support": true,
            "has_triggers": true,
            "validation_supported": true,
            "available_triggers": [
                {
                    "id": "orders/create",
                    "name": "Created order",
                    "description": "Triggered when a new sale order is created"
                },
                {
                    "id": "orders/delete",
                    "name": "Deleted order",
                    "description": "Triggered when a sale order is deleted"
                },
                {
                    "id": "products/create",
                    "name": "Created product",
                    "description": "Triggered when a new product is created"
                },
                {
                    "id": "products/delete",
                    "name": "Deleted product",
                    "description": "Triggered when a product is deleted"
                }
            ],
            "config": {
                "start_date": "2015-01-01T00:00:00.000Z",
                "date_window_size": 365
            },
            "schemaTables": [
                "SalesOrders"
            ],
            "hg_schema": "ecommerce"
        },
        "isForked": true
    }

Understanding the Connector Fields

`id`

The id field is a unique identifier for the connector. It is used internally to reference the connector and should be unique across all connectors.

`label`

The label field is a human-readable name for the connector. This is the name that will be displayed in the user interface.

`icon`

The icon field is a URL to an image that represents the connector. This icon will be displayed in the user interface alongside the connector’s label.

`tags`

The tags field is an array of strings that categorize the connector. These tags can be used to filter and search for connectors.

`domain`

The domain field specifies the primary domain associated with the connector. This is typically the domain of the service the connector integrates with.

`type`

The type field specifies the authentication method used by the connector. Accepted values are oauth and api

`read_connector` and `write_connector`

These fields specify the github repo of the tap and target respectively. The following sub-fields are supported inside read_connector and write_connector:

Field	Type	Description
`id`	string	Unique identifier for the tap or target
`install_uri`	string	Custom git install URI. Overrides the default installation source
`connector_repo`	string	Full git repository URL for the tap or target. Only works with hotglue-maintained repositories
`connector_tag`	string	Version tag of the repository to install. Only works with hotglue-maintained repositories
`singer_sdk`	boolean	Indicates this tap or target is built using the Singer SDK
`is_private_repo`	boolean	Uses your configured git access token to install from a private repository. See Private Repositories for more details.
`static_data`	boolean	Indicates this tap serves static pre-loaded data rather than live API data
`validation_disabled`	boolean	Disables credential validation for this tap during account linking
`tap_driver_name`	string	Overrides the default driver name used to run the connector. Use this when the driver name differs from the connector `id`

If the connector uses a custom branch of a git repo, you can set a custom install uri:

"write_connector": {
    "id": "shopify-v2",
    "install_uri": "git+https://gitlab.com/hotglue/target-shopify-v2.git@bump-to-use-new-target-sdk"
},

If that repository is private, you can add the is_private_repo flag to use your configured git access token when installing your connector.

"write_connector": {
    "id": "shopify-v2",
    "install_uri": "git+https://gitlab.com/hotglue/target-shopify-v2.git@bump-to-use-new-target-sdk"
    "is_private_repo": true
},

If the connector uses a tagged release of a repository, you can specify that connector tag:

    "connector_repo": "git+https://github.com/hotgluexyz/target-redshift.git",
    "connector_tag": "^v1.6.1",
    "singer_sdk": true

`isForked`

The isForked field indicates whether this connector has been modified from the default Hotglue connector settings.

`formattable_fields`

The formattable_fields flag allows you to set a list of config flags that can be used as variables for your auth URLs.

"formattable_fields": ["shop", "tenant_id"]

For example, if you set:

"auth_url": "https://{shop}.shopify.com/token"

And the tenant has config:

{
  ...
  "shop": "usa",
  ...
}

then hotglue will use the following auth_url when completing the OAuth flow:

https://usa.shopify.com/token

All fields specified in the connect_ui_params are used as formattable_fields by default.

`isConnector`

The isConnector field marks whether this entry is a bi-directional connector.

"isConnector": true,
"isSource": false,
"isTarget": false

`isSource`

The isSource field marks whether this connector can act as the source in a V2 bidirectional flow.

`isTarget`

The isTarget field marks whether this connector can act as the target in a V2 bidirectional flow.

`version`

The version field adds a version label chip to the connector card in the UI. This helps tenants identify which version of the connector they are using.

"version": "v2"

`auth_url`

The auth_url field specifies the OAuth authorization URL used to initiate the authentication flow for this connector.

"auth_url": "https://app.example.com/oauth/authorize"

`token_url`

The token_url field specifies the OAuth token exchange URL used to obtain access tokens after the tenant has authorized the connector.

"token_url": "https://app.example.com/oauth/token"

`revoke_url`

The revoke_url field specifies the URL called to revoke OAuth tokens when a tenant disconnects the connector.

"revoke_url": "https://app.example.com/oauth/revoke"

`dynamic_urls`

The dynamic_urls field allows the connector to construct URLs dynamically at runtime using tenant-specific config values. When set to true, placeholders in auth_url and token_url are replaced with values from the tenant’s config. For example, Zoho uses a region-specific URL selected by the tenant:

"auth_url": "{uri}/oauth/v2/auth?response_type=code&scope=ZohoInventory.FullAccess.all",
"token_url": "{uri}/oauth/v2/token",
"dynamic_urls": true,
"connect_ui_params": {
    "uri": {
        "label": "Zoho Region",
        "type": "select",
        "options": [
            { "name": "US", "value": "https://accounts.zoho.com" },
            { "name": "EU", "value": "https://accounts.zoho.eu" }
        ]
    }
}

When a tenant selects EU, hotglue replaces {uri} with https://accounts.zoho.eu in the auth and token URLs automatically.

`connector_repo`

The connector_repo field specifies the git repository URL for a hotglue-maintained connector. This field only works with hotglue-maintained repositories.

"connector_repo": "git+https://github.com/hotgluexyz/tap-sharepoint.git"

`connector_tag`

The connector_tag field specifies the version tag of a hotglue-maintained connector repository to install. This field only works with hotglue-maintained repositories.

"connector_tag": "^v1.0.0"

`oauth_settings`

The oauth_settings field contains advanced OAuth configuration for the connector. The following sub-fields are supported:

Field	Type	Description
`use_pkce_verifier`	boolean	Enables PKCE (Proof Key for Code Exchange) for enhanced OAuth security
`use_basic_auth`	boolean	Sends client credentials using HTTP Basic Auth during token exchange
`use_json_payload`	boolean	Sends the token request as a JSON payload instead of form-encoded data
`no_code_param`	boolean	Omits the code parameter from the token request for non-standard OAuth flows
`encode_state`	boolean	Encodes the OAuth state parameter before sending

"oauth_settings": {
    "use_pkce_verifier": true
}

`connect_ui_params`

The connect_ui_params field defines the fields shown to tenants in the connection UI. Each field key maps to a parameter object that supports the following properties:

Property	Type	Description
`label`	string	Human-readable label shown to the tenant for this field
`description`	string	Helper text displayed below the field to guide the tenant
`type`	string	Input type for the field. Accepted values: `password`, `boolean`, `select`, `number`, `list`, `multiline`. Defaults to text if not specified
`required`	boolean	Whether this field is required for the tenant to connect. Defaults to `true` if not specified
`adornment`	object	Adds prefix or suffix text around the input field
`adornment.start`	string	Text displayed before the input field (e.g. `https://`)
`adornment.end`	string	Text displayed after the input field (e.g. `.myshopify.com`)
`options`	array	Used when `type` is `select`. Defines the list of options the tenant can choose from
`options[].name`	string	Display name for the select option
`options[].value`	string	Value submitted when this option is selected
`params`	object	Used when `type` is `list`. Defines the sub-fields for each item in the list

The following examples show fields using different property combinations:

"connect_ui_params": {
    "shop": {
        "label": "Shop",
        "description": "Your Shopify shop name",
        "adornment": {
            "start": "https://",
            "end": ".myshopify.com"
        }
    },
    "region": {
        "label": "Region",
        "type": "select",
        "options": [
            { "name": "North America", "value": "https://www.amazon.com" },
            { "name": "Europe", "value": "https://www.amazon.co.uk" }
        ]
    },
    "bulk": {
        "label": "Bulk",
        "type": "boolean",
        "required": false
    },
    "api_key": {
        "label": "API Key",
        "description": "Your API Key",
        "type": "password"
    }
}

`options`

The options field is a container for advanced connector configuration. The following sub-fields are supported:

Field	Type	Description
`validation_supported`	boolean	Indicates whether the connector validates tenant credentials during account linking
`no_fieldmap`	boolean	Disables field mapping for this connector
`no_refresh`	boolean	Disables automatic token refresh for this connector
`force_redirect`	boolean	Forces the OAuth redirect flow even when not strictly required
`autogen_fieldmap`	boolean	Automatically generates a field map for this connector
`disabled`	boolean	Marks this connector as disabled and unavailable for use
`dynamic_urls`	boolean	Enables dynamic URL construction using tenant config values
`basic_client_credentials`	boolean	Uses HTTP Basic Auth for client credentials instead of standard OAuth
`unified_version`	string	Specifies the unified schema version used by this connector (e.g. `v2`)
`connector_type`	string	Specifies the connector runtime type (e.g. `airbyte`)
`revoke_url`	string	URL to revoke OAuth tokens when a tenant disconnects. Used by some connectors inside `options`
`customLoginButton`	string	Specifies a custom login button style shown in the connection UI (e.g. `google`)
`external_repo_url`	string	URL to the external repository for airbyte-sourced connectors
`config`	object	Defines default config values automatically applied to every new tenant. See Default configs below

"options": {
    "validation_supported": true,
    "dynamic_urls": true
}

Default configs

The config block is a sub-key of options. It defines default configuration values that are automatically applied to every new tenant connecting to this connector. Tenants inherit these values without needing to configure them manually. The only universal config field supported across all connectors is start_date. All other config fields are connector-specific — refer to the individual connector’s documentation for the full list of supported fields.

Field	Type	Description
`start_date`	string	Default start date for data sync in ISO 8601 format

"options": {
    "config": {
        "start_date": "2000-01-01T00:00:00.000Z"
    }
}

Getting Started

Key Concepts

Managed authentication

Transformation

Custom Connectors

Unified Schema

Environment Settings

CLI

Connectors

Connector Settings

What are Connector Settings?

Example Connector Settings

Understanding the Connector Fields

`id`

`label`

`icon`

`tags`

`domain`

`type`

`read_connector` and `write_connector`

`isForked`

`formattable_fields`

`isConnector`

`isSource`

`isTarget`

`version`

`auth_url`

`token_url`

`revoke_url`

`dynamic_urls`

`connector_repo`

`connector_tag`

`oauth_settings`

`connect_ui_params`

`options`

Default configs

​What are Connector Settings?

​Example Connector Settings

​Understanding the Connector Fields

​id

​label

​icon

​tags

​domain

​type

​read_connector and write_connector

​isForked

​formattable_fields

​isConnector

​isSource

​isTarget

​version

​auth_url

​token_url

​revoke_url

​dynamic_urls

​connector_repo

​connector_tag

​oauth_settings

​connect_ui_params

​options

​Default configs

What are Connector Settings?

Example Connector Settings

Understanding the Connector Fields

`id`

`label`

`icon`

`tags`

`domain`

`type`

`read_connector` and `write_connector`

`isForked`

`formattable_fields`

`isConnector`

`isSource`

`isTarget`

`version`

`auth_url`

`token_url`

`revoke_url`

`dynamic_urls`

`connector_repo`

`connector_tag`

`oauth_settings`

`connect_ui_params`

`options`

Default configs