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 to authenticate 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 your connection with {{config.key}}.

Connection settings

A connection has these core settings:

• Base URL — the root URL of the API. Every request path in your flows is appended to this. You can embed configuration values here (see below), for example to switch between a sandbox and a live endpoint.
• Timeout — how long, in milliseconds, to wait for the API to respond before giving up.
• Retry count — how many times a request is attempted in total before giving up (default 3 — one initial attempt plus up to two retries).
• Allow insecure SSL — when enabled, the connection will accept self-signed or otherwise untrusted SSL certificates. Use this only for trusted private or internal panels on your own network, never for public internet endpoints.

Authentication types

Choose the authentication type that matches what the external API expects, then fill in its fields. The available types and their fields are:

Auth type	What you provide
None	Nothing — used when the API needs no credentials, or when the token is already embedded in the base URL.
API Key	A key name (the header or parameter name the API expects, e.g. X-API-Key), the key value, and a location (header or query parameter).
Bearer Token	The token value, sent as Authorization: Bearer ….
Basic Auth	A username and password, sent as standard HTTP Basic authentication.
OAuth2 Token	A pre-obtained access token, sent as Authorization: Bearer ….
Custom Header	One or more named headers with their values — for APIs that authenticate via a header that doesn't fit the patterns above. The wizard supports one header; more can be added after creation from the Connections tab.
Query Parameters	One or more named query parameters with their values, appended to the request URL — for APIs that authenticate via the query string. The wizard supports one parameter; more can be added after creation.
HMAC Body Signature	A signing key, the algorithm to sign with, the signature header name the signature is placed in, and the body encoding used when computing the signature. The connection signs each request body and adds the signature header automatically. This type is available from the plugin editor's Connections tab after the plugin is created.

The New Plugin wizard offers seven auth types in Step 3 (all except HMAC Body Signature). HMAC Body Signature is added from the plugin's Connections tab after creation.

Keeping secrets safe

Credentials you enter are stored encrypted. They are masked on screen, and — importantly — they are never included when you export or share a plugin. This means you can safely package and distribute a plugin: whoever installs it supplies their own credentials, and yours never leave your instance. See Packaging, Importing, and Updating.

Pulling configuration into your connection

You usually don't want to hard-code values like the base URL or an account-specific path. Instead, reference your plugin's configuration settings with the {{config.key}} syntax — wherever key is the key of a field in your configuration schema. You can use these references inside the base URL and inside header 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, FluxBilling substitutes the operator's saved configuration value 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 configuration setting — say 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 simply picks the mode in their plugin settings, and every request your flows make is routed to the right environment. (See Configuration Settings for how to define Select fields.)

Testing the connection

Use the Test button to fire a quick request against the connection and confirm your base URL and authentication are correct. Test early and often while your plugin is still a Draft — catching a bad credential or wrong URL here is far easier than debugging it inside a flow.

---

Related: Creating a Plugin · Configuration Settings · Variables and Expressions