Feature Guide

Custom Connections Agent

The Custom Connections Agent lets GTMship work with both built-in providers and custom APIs. It handles provider metadata, auth mode selection, credential storage, and the runtime path your workflow uses to reach external systems.

Provider catalog Custom APIs OAuth2 + API keys Encrypted credentials

What it does

Connections connect a workflow draft to a real external system. GTMship includes a provider catalog for common tools, but the Custom Connections Agent also supports custom APIs when you bring docs or an OpenAPI specification.

What GTMship needs to model a provider

Base URL and environment shape

The agent needs to know where the API lives and whether production, staging, or tenant-specific hosts change the request path.

Auth method and token behavior

OAuth, API key, and basic auth all behave differently, so GTMship needs the right auth shape before it can generate safe connection flows.

Endpoint or operation references

OpenAPI specs, endpoint docs, or structured examples help the workflow agent ground request formats before it writes integration code.

Example payloads or fields

Representative request and response shapes make it easier to map business objects and avoid vague field assumptions in generated workflows.

Auth modes GTMship supports

OAuth2

Use redirect-based auth for providers such as CRMs and messaging tools, with token refresh managed through the auth service.

API key

Store API keys as encrypted connection credentials so workflows can call systems without hardcoding secrets.

Basic auth

Handle username and password style credentials when an API exposes that auth shape.

Shared OAuth families

Some provider families can reuse a single shared app configuration instead of reauthorizing each related service separately.

How onboarding works

  1. Select a built-in connector or start a custom provider from docs.
  2. Define provider metadata such as base URL, auth type, and available endpoints.
  3. Create a connection using OAuth, API key, or basic auth.
  4. Store credentials behind the auth service instead of inside workflow source.
  5. Bind that connection into workflows during generation, preview, and deployment.
Provider docs
  -> provider config
  -> connection credentials
  -> workflow binding
  -> runtime auth resolution

Provider definitions vs connection records

Provider definition

The reusable API model

This captures things like base URL, auth expectations, and the operations GTMship should reason about when building workflows.

Connection record

The authorized account or secret set

This is the actual credentialed relationship to a tenant, workspace, or account that gets bound into preview and deployment.

Runtime auth strategies

Proxy mode

Simpler local and hosted flow

Workflow calls go through the auth-service proxy, which resolves the bound connection, injects auth headers, and can refresh expired OAuth tokens.

Secret manager mode

Cloud-native secret replication

Active credentials are replicated into AWS Secrets Manager or GCP Secret Manager, and deployments receive deterministic secret references in their runtime manifest.

Proxy mode is usually the simpler path while iterating locally. Secret-manager mode is helpful when the deployed runtime should read credentials directly from your cloud environment.

When custom APIs fit best

  • Your team has an internal service with a stable REST API.
  • You need a tool GTMship has not shipped as a built-in connector yet.
  • You want the workflow agent to reason over the provider docs before generating code.

Related docs

How the Workflow Builder Agent uses grounded APIs How bindings resolve at deploy time Where to manage connections