connectionConfigVar()

Creates a connection config variable for code-native integrations.

The connectionConfigVar() function defines a config variable that holds a connection — a set of authentication credentials (API key, OAuth token, username/password, etc.) used to authenticate with an external service. Connection config variables always have dataType: "connection".

A connection config var can be defined in two ways:

• Connection definition — inline definition with explicit inputs fields (used when building a connection from scratch within a code-native integration).
• Connection reference — a reference to a connection defined in a component registered in the componentRegistry (used when reusing an existing component’s connection type).

Function signature

export const connectionConfigVar = <T extends ConnectionConfigVar = ConnectionConfigVar>(
  definition: T,
): T

Parameters

definition · ConnectionConfigVar · required

An object describing the connection config variable. The shape depends on whether it is a connection definition or a connection reference.

Hide Common fields (all connection config vars)

stableKey · string · required

A unique, unchanging identifier for this connection config variable.

dataType · 'connection' · required

Must always be "connection" for connection config variables.

description · string

Human-readable description shown in the config wizard.

permissionAndVisibilityType · 'customer' | 'embedded' | 'organization' · default: "customer"

Controls who can view and edit this connection in the config wizard.

visibleToOrgDeployer · boolean · default: "true"

Whether this connection is visible to an organization deployer.

Show Connection definition fields (inline connection)

inputs · Record<string, InputField & ConfigVarInputVisibility> · required

The input fields that make up the connection (e.g., apiKey, baseUrl, username, password). Each value is an input field definition combined with optional visibility settings.

icons · object

Optional icons to display in the config wizard for this connection.

onPremConnectionConfig · 'allowed' | 'disallowed' | 'required'

Whether the connection supports on-premise agents.

Show Connection reference fields (component connection)

connection · ComponentReference & { template?: string; onPremiseConnectionConfig?: 'allowed' | 'disallowed' | 'required' } · required

A reference to a connection defined in a component from the componentRegistry. Includes the component key, connection key, and any input values.

Show connection fields

component · string · required

The key of the component that defines this connection.

key · string · required

The key of the specific connection within the component.

values · object

Input values for the connection, where each value is a ValueExpression or ConfigVarExpression.

template · string

Optional template string.

onPremiseConnectionConfig · 'allowed' | 'disallowed' | 'required'

On-premise configuration, only available if the component connection supports on-premise agents.

Return type

connectionConfigVar · T

The same connection config variable definition object passed in, unchanged. Used for type inference.

At runtime, the value of a connection config variable is available as a Connection object in context.configVars. It contains the resolved input values and can be passed directly to component actions or used in your own HTTP client setup.

Examples

Inline connection definition

import { configPage, connectionConfigVar, input } from "@prismatic-io/spectral";

const connectionPage = configPage({
  tagline: "Authenticate with Acme Corp API",
  elements: {
    "Acme Connection": connectionConfigVar({
      stableKey: "acme-connection",
      dataType: "connection",
      description: "Your Acme Corp API credentials.",
      inputs: {
        apiKey: input({
          label: "API Key",
          type: "password",
          required: true,
          comments: "Your Acme Corp API key.",
          clean: (value) => String(value),
        }),
        baseUrl: input({
          label: "Base URL",
          type: "string",
          required: true,
          default: "https://api.acme.com/v1",
          comments: "The base URL for the Acme Corp API.",
          clean: (value) => String(value),
        }),
      },
    }),
  },
});

Customer-activated and organization-activated connections

For integration-agnostic connections, use the dedicated helper functions instead of connectionConfigVar():

• customerActivatedConnection({ stableKey }) — Creates a customer-activated connection config var (customers configure the connection themselves).
• organizationActivatedConnection({ stableKey }) — Creates an org-activated connection config var (the organization configures the connection, not the customer).

These are placed in scopedConfigVars on the integration definition rather than in configPages.

import {
  integration,
  organizationActivatedConnection,
} from "@prismatic-io/spectral";

export default integration({
  name: "My Integration",
  flows: [],
  scopedConfigVars: {
    "Shared API Connection": organizationActivatedConnection({
      stableKey: "shared-api-connection",
    }),
  },
});

Related

• configPage() — The page that contains this connection config variable.
• configVar() — For non-connection config variables.
• componentManifest() — Register component connections for reference.
• integration() — The parent integration definition.