Connections & Authentication

A connection is how your plugin reaches the external API it integrates with — the base URL, the request settings, and the credentials used on every call. Your flows make their HTTP requests through a connection, so getting this right is the foundation of a working plugin. This article covers the connection settings, every authentication type and the fields each one needs, how secrets are protected, and how to pull configuration values into a connection with {{config.key}}.

How to reach it

Open Settings → Integrations → Plugins, open your plugin, and choose the Connections tab. Each connection is listed with its name, base URL and authentication type, plus buttons to test, edit, clone and delete it. When a connection has been tested, the row shows Last tested with the time and, on failure, the error returned.

Connection settings

Fields in the Add / Edit Connection dialog

Field	What it does
Name	A readable label for this connection. Required.
Slug	The stable identifier your flow nodes use to address this connection. Leave it blank on create and it is derived from the name. It cannot be changed after the connection exists — flows reference it by slug — and the field is read-only when editing.
Base URL	The root URL of the API. Every request path in your flows is appended to it. Required.
Authentication Type	How the API is authenticated. Picking a type reveals its own fields (see below).
Default Headers	Name/value pairs sent on every request through this connection, on top of the authentication headers.
Timeout (ms)	How long to wait for a response before giving up. Default 30000; accepted range 1000–300000.
Retry Count	How many attempts a request gets in total. Default 3, range 0–5. Only transient network failures are retried (connection refused or reset, timed out, host not found) — an HTTP error status is never retried, it is returned to your flow so you can branch on it. Waits between attempts grow with each retry.
Allow insecure SSL certificates	When ticked, the connection accepts self-signed or otherwise untrusted certificates, and also permits addresses on private networks. Use it only for a trusted panel on your own network, never for a public endpoint.

Note: requests are blocked when the target resolves to a loopback, link-local or cloud-metadata address, or uses anything other than http or https. Private network ranges are blocked too unless Allow insecure SSL certificates is on. The same check applies when a flow builds an absolute URL in a request path.

Authentication types

Choose the type that matches what the external API expects, then fill in its fields.

Authentication types and their fields

Auth type	What you provide
None	Nothing. Use it when the API needs no credentials, or when the credential is already embedded in the base URL through a {{config.…}} reference.
API Key	Header Name (defaults to X-API-Key if left blank) and API Key. The key is sent in that request header.
Bearer Token	Token, plus two optional fields: Token Secret Key (the name of the stored secret to read the token from, when it isn't the default) and Token Prefix (defaults to Bearer). Sent as Authorization: <prefix> <token>.
Basic Auth	Username and Password, sent as standard HTTP Basic authentication.
Query Parameters	A list of query parameter name/value rows appended to every request URL. Values may contain {{secret_name}} placeholders; a masked input for each referenced secret appears underneath as you type.
OAuth2 Token	A pre-obtained Access Token, sent as Authorization: Bearer ….
Custom Header	A list of Auth Headers name/value rows, for APIs whose header doesn't fit the patterns above. As with query parameters, values may contain {{secret_name}} placeholders and a masked input appears for each one referenced.
HMAC Body Signature	Algorithm (sha256, sha1 or sha512), Signature Header (the header the signature is placed in, default X-Signature), Body Encoding (raw or base64), an optional HMAC Key Field naming the stored secret that holds the signing key (default api_key), the secret itself, and optional Static Headers. The request body is signed on every call and the signature header added for you.
Avangate HMAC (2Checkout)	Merchant Code Field and Secret Key Field (the names of the stored secrets holding each value) and an Algorithm of sha256 or sha3-256. The signature header, including the timestamp the scheme requires, is built for you.

The New Plugin wizard offers a shorter list in its optional connection step — None, API Key, Bearer Token, Basic Auth, OAuth2 Token, Custom Header and Query Parameters, one header or parameter each. The Connections tab is the full editor: open it after creating the plugin to review the connection, add further headers or parameters, and set the timeout, retry count and default headers.

Keeping secrets safe

Credentials you enter are stored encrypted. They are masked on screen behind an eye toggle, and they are never included when you export or share a plugin — the package describes how a connection authenticates, not the keys behind it. That is what makes a plugin safe to distribute: whoever installs it supplies their own credentials, and yours never leave your installation. Cloning a connection copies its settings but not its secrets, and the dialog says so. See Packaging, Importing & Updating.

Pulling configuration into your connection

You usually don't want to hard-code values like the base URL or an account-specific host. Reference your plugin's configuration settings instead, with {{config.key}}, where key is the key of a field in your configuration schema. These references work in the Base URL, in header values and in query parameter values.

For example, if your configuration has a field with the key region, your base URL might be:

https://{{config.region}}.api.example.com

When a flow runs, the saved configuration value is substituted in place of the reference.

Worked example: switching sandbox and live

A common pattern is letting the operator flip between a sandbox and a production environment without editing the connection. Add a Select field with the key mode whose options are the sandbox and live hostnames, then reference it in the base URL:

https://{{config.mode}}/v1

Now the operator picks the mode in the plugin's Config screen and every request is routed to the right environment. An alternative is to create two connections — say sandbox-api and live-api — and let the HTTP Request node choose between them with a templated Connection Slug Override such as {{config.mode}}-api. (See Configuration Settings for how to define Select fields, and Node Reference for the override field.)

Testing the connection

The test button on a connection row fires a request at the connection's root and reports success with the returned status, or the error. The result is stored, so the row afterwards shows Last tested with the time and outcome. Test early and often while your plugin is still a Draft — catching a bad credential or a wrong URL here is far easier than diagnosing it from inside a flow.

---

Related: Creating a Plugin · Configuration Settings · Variables & Expressions · Node Reference