connection

Define a connection that stores credentials and configuration for authenticating with an external service.

The connection function creates a connection definition for use in custom components and code-native integrations. Connections bundle a set of credential fields (such as an API key or base URL) that integration builders configure once and reference across multiple action steps.

Function signature

function connection<T extends DefaultConnectionDefinition>(definition: T): T

Parameters

definition · DefaultConnectionDefinition · required

An object describing the connection. See fields below.

DefaultConnectionDefinition fields

definition.key · string · required

A unique programmatic identifier for this connection type within the component.

definition.display · ConnectionDisplayDefinition · required

Controls how the connection appears in the Prismatic UI.

Show ConnectionDisplayDefinition fields

display.label · string · required

Human-readable name for the connection (e.g., "API Key").

display.description · string · required

Describes what this connection is for.

display.icons · object

Optional icon paths for the connection UI.

Show icons fields

display.icons.avatarPath · string

Path to an avatar icon, relative to the built component source.

display.icons.oauth2ConnectionIconPath · string

Path to an icon for the OAuth “Connect” button, relative to the built component source.

definition.inputs · Record<string, ConnectionInput> · required

A map of input field definitions that the integration builder fills in to configure this connection. Uses ConnectionInput — a variant of the standard input field that omits the clean function and adds shown and writeOnly options.

Show ConnectionInput fields

inputs[key].type · 'string' | 'data' | 'text' | 'password' | 'boolean' | 'template' · required

The type of the connection input field.

inputs[key].label · string | { key: string; value: string } · required

Display label for this field.

inputs[key].required · boolean

Whether this field must be filled in.

inputs[key].placeholder · string

Placeholder text.

inputs[key].comments · string

Help text for this field.

inputs[key].example · string

Example valid value.

inputs[key].default · string

Default value.

inputs[key].shown · boolean

When false, hides this field from the integration builder UI. Defaults to true.

inputs[key].writeOnly · true

When set, this field’s value is write-only and never returned in API responses. Use for secrets. See write-only inputs.

inputs[key].model · InputFieldChoice[]

Dropdown choices for this field.

Return type

Returns the same DefaultConnectionDefinition object passed in, after validation. Pass the returned value to the connections array in component.

Example

import { connection, component } from "@prismatic-io/spectral";

export const apiKeyConnection = connection({
  key: "apiKey",
  display: {
    label: "API Key",
    description: "Authenticate using an API key",
  },
  inputs: {
    endpoint: {
      label: "API Endpoint",
      type: "string",
      required: true,
      default: "https://api.example.com",
      placeholder: "https://api.example.com",
      comments: "The base URL of the API",
      example: "https://api.acme.com",
    },
    apiKey: {
      label: "API Key",
      type: "password",
      required: true,
      shown: true,
      writeOnly: true,
      placeholder: "Your API key",
    },
    region: {
      label: "Region",
      type: "string",
      required: false,
      model: [
        { label: "US East", value: "us-east" },
        { label: "EU West", value: "eu-west" },
      ],
      default: "us-east",
    },
  },
});

export default component({
  key: "myComponent",
  display: {
    label: "My Component",
    description: "Example component",
    iconPath: "icon.png",
  },
  connections: [apiKeyConnection],
});

Using a connection in an action

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

export const fetchData = action({
  display: { label: "Fetch Data", description: "Get data from the API" },
  inputs: {
    connection: input({ label: "Connection", type: "connection", required: true }),
  },
  perform: async (context, params) => {
    const { endpoint, apiKey } = params.connection.fields as {
      endpoint: string;
      apiKey: string;
    };

    const response = await fetch(`${endpoint}/data`, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });

    return { data: await response.json() };
  },
});

Related

• oauth2Connection — Define an OAuth 2.0 connection
• onPremConnection — Define an on-premises connection
• component — Register connections in a component
• input — Define inputs for actions that accept a connection