Skip to main content
A connection defines how integration builders authenticate with a third-party service. Connections are attached to a component via the connections array in component() and are referenced by actions and triggers via a connection input. Spectral provides four functions for defining connections:
FunctionUse case
connection()API key, username/password, or any non-OAuth scheme
oauth2Connection()OAuth 2.0 (authorization code or client credentials)
onPremConnection()Connections that route through an on-prem agent

​
Standard connections

Use connection() for connections backed by static credentials such as API keys or username/password pairs. 
interface DefaultConnectionDefinition {
  key: string;
  display: ConnectionDisplayDefinition;
  oauth2Type?: OAuth2Type; // omit for non-OAuth connections
  inputs: {
    [key: string]: ConnectionInput;
  };
}
ConnectionDisplayDefinition supports an optional icons object for customizing the appearance of the connection card: 
interface ConnectionDisplayDefinition {
  label: string;
  description: string;
  icons?: {
    /** Path to avatar icon shown on the connection card. */
    avatarPath?: string;
    /** Path to icon used for the OAuth "Connect" button. */
    oauth2ConnectionIconPath?: string;
  };
}

​
API key example

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

export const apiKeyConnection = connection({
  key: "apiKey",
  display: {
    label: "My API — API Key",
    description: "Authenticate with My API using a secret API key",
  },
  inputs: {
    apiKey: {
      label: "API Key",
      type: "password",
      required: true,
      comments: "Your API key from the My API developer portal",
      placeholder: "sk-live-...",
    },
    baseUrl: {
      label: "Base URL",
      type: "string",
      required: false,
      default: "https://api.example.com",
      comments: "Override to point to a sandbox or self-hosted instance",
    },
  },
});

​
Username and password example

export const basicAuthConnection = connection({
  key: "basicAuth",
  display: {
    label: "My API — Username & Password",
    description: "Authenticate with My API using a username and password",
  },
  inputs: {
    username: {
      label: "Username",
      type: "string",
      required: true,
    },
    password: {
      label: "Password",
      type: "password",
      required: true,
    },
  },
});

​
ConnectionInput fields

ConnectionInput is a subset of InputFieldDefinition with two additional fields:
FieldTypeDescription
type"string" | "data" | "text" | "password" | "boolean"Input field type
labelstringDisplay label
requiredbooleanWhether the field is required
defaultstringDefault value
placeholderstringPlaceholder text
commentsstringHelp text shown below the field
examplestringExample value shown in the UI
shownbooleanWhether to show this field in the UI (default true)
writeOnlytrueMark the field as write-only (value is never read back)

​
OAuth 2.0 connections

Use oauth2Connection() for OAuth 2.0 flows. Prismatic handles the token exchange and refresh automatically.

​
OAuth2Type enum

enum OAuth2Type {
  ClientCredentials = "client_credentials",
  AuthorizationCode = "authorization_code",
}
Authorization code flow redirects the user to the third-party login page to grant access.
import { oauth2Connection, OAuth2Type } from "@prismatic-io/spectral";

export const oauthConnection = oauth2Connection({
  key: "oauth2",
  display: {
    label: "My API — OAuth 2.0",
    description: "Authenticate with My API using OAuth 2.0",
  },
  oauth2Type: OAuth2Type.AuthorizationCode,
  inputs: {
    authorizeUrl: {
      label: "Authorization URL",
      type: "string",
      default: "https://auth.example.com/oauth/authorize",
      required: true,
    },
    tokenUrl: {
      label: "Token URL",
      type: "string",
      default: "https://auth.example.com/oauth/token",
      required: true,
    },
    scopes: {
      label: "Scopes",
      type: "string",
      default: "read write",
      required: true,
    },
    clientId: {
      label: "Client ID",
      type: "string",
      required: true,
    },
    clientSecret: {
      label: "Client Secret",
      type: "password",
      required: true,
    },
  },
});

​
OAuth2UrlOverrides

You can override the Prismatic OAuth 2.0 redirect URIs using oauth2Config on an authorization code connection: 
export const oauthWithCustomRedirect = oauth2Connection({
  key: "oauth2CustomRedirect",
  display: { label: "My API", description: "" },
  oauth2Type: OAuth2Type.AuthorizationCode,
  oauth2Config: {
    oAuthSuccessRedirectUri: "https://app.example.com/oauth/success",
    oAuthFailureRedirectUri: "https://app.example.com/oauth/failure",
  },
  inputs: { /* ... */ },
});

​
PKCE support

To enable PKCE (Proof Key for Code Exchange) on an authorization code connection, set oauth2PkceMethod: 
import { oauth2Connection, OAuth2Type, OAuth2PkceMethod } from "@prismatic-io/spectral";

export const pkceConnection = oauth2Connection({
  key: "oauth2Pkce",
  display: { label: "My API — OAuth 2.0 with PKCE", description: "" },
  oauth2Type: OAuth2Type.AuthorizationCode,
  oauth2PkceMethod: OAuth2PkceMethod.S256, // or OAuth2PkceMethod.Plain
  inputs: { /* ... */ },
});
OAuth2PkceMethod has two values:
ValueDescription
OAuth2PkceMethod.S256SHA-256 challenge method (recommended)
OAuth2PkceMethod.PlainPlain text challenge method

​
On-prem connections

Use onPremConnection() when the third-party service runs inside a customer’s private network. Prismatic replaces the host and port values with a local tunnel endpoint when the on-prem agent is active. 
interface OnPremConnectionDefinition {
  key: string;
  display: ConnectionDisplayDefinition;
  inputs: {
    host: OnPremConnectionInput; // Required
    port: OnPremConnectionInput; // Required
    [key: string]: ConnectionInput;
  };
}

// OnPremConnectionInput must include onPremControlled: true
type OnPremConnectionInput = { onPremControlled: true } & ConnectionInput;

import { onPremConnection } from "@prismatic-io/spectral";

export const databaseConnection = onPremConnection({
  key: "onPremDatabase",
  display: {
    label: "On-Prem Database",
    description: "Connect to a database inside the customer's network",
  },
  inputs: {
    host: {
      label: "Host",
      type: "string",
      required: true,
      onPremControlled: true,
      comments: "Database hostname (overridden by on-prem agent)",
    },
    port: {
      label: "Port",
      type: "string",
      required: true,
      onPremControlled: true,
      default: "5432",
    },
    username: {
      label: "Username",
      type: "string",
      required: true,
    },
    password: {
      label: "Password",
      type: "password",
      required: true,
    },
    database: {
      label: "Database Name",
      type: "string",
      required: true,
    },
  },
});

​
templateConnectionInputs helper

templateConnectionInputs() merges your custom inputs with template (hidden) inputs that are computed from other field values. This is useful for constructing a full URL from a base URL template without exposing the computed value to users: 
import { connection, templateConnectionInputs } from "@prismatic-io/spectral";

export const templatedConnection = connection({
  key: "templated",
  display: { label: "My API", description: "" },
  inputs: templateConnectionInputs(
    {
      subdomain: {
        label: "Subdomain",
        type: "string",
        required: true,
        placeholder: "my-company",
      },
    },
    {
      baseUrl: {
        label: "Base URL",
        type: "template",
        // Constructs the URL from the subdomain input
        templateValue: "https://{{subdomain}}.example.com/api",
      },
    }
  ),
});

​
Reading connection values in actions

When a user configures a connection, the field values are available via the connection input parameter in the action’s perform function: 
perform: async (context, params) => {
  const { connection } = params;

  // Static credential fields
  const apiKey = connection.fields.apiKey as string;

  // OAuth 2.0 access token (managed by Prismatic)
  const accessToken = connection.token?.access_token as string;

  // OAuth 2.0 token metadata
  const tokenExpiry = connection.context?.expires_at;
}
Never log connection field values. The password type is masked in the Prismatic UI but the raw value is accessible in the perform function. Use context.logger only for non-sensitive metadata.