connectionConfigVar()

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

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

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",
    }),
  },
});

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.

Core Functions

Code-Native Integration Functions

Testing Utilities

Utility Module

connectionConfigVar()

Function signature

Parameters

Return type

Examples

Customer-activated and organization-activated connections

Build docs developers (and LLMs) love

Core Functions

Code-Native Integration Functions

Testing Utilities

Utility Module

​Function signature

​Parameters

​Return type

​Examples

​Customer-activated and organization-activated connections

​Related

Build docs developers (and LLMs) love

Function signature

Parameters

Return type

Examples

Customer-activated and organization-activated connections

Related