Build Your First Connector

A StackOne connector is a YAML configuration that turns a third-party API into a set of agent-ready actions. By the end of this guide, you’ll have a working connector pushed to your StackOne project — built with the StackOne CLI, an AI assistant, and the connectors-template. You’ll set up your environment, generate an API key, build and test authentication against a provider, then add and validate your first actions.

Custom connectors require Enterprise access — contact support@stackone.com to enable.

Setup

Generate a StackOne API key

In the StackOne dashboard, go to Project Settings → API keys.
Click Create API key.
Ensure the following Scopes are enabled (some are not selected by default):
- connectors:read — download connectors from registry
- connectors:write — push and delete connectors
- credentials:read — use linked account credentials with stackone run
Copy the key (format: v1.{region}.xxxxx) and store it somewhere safe — you won’t be able to view it again.

See API Keys for more on scopes.

Open a Terminal & Install the StackOne CLI

You’ll run all StackOne CLI commands from a terminal window.

macOS
Windows
Linux

Press Cmd + Space to open Spotlight, type Terminal, and press Enter.
Confirm Node.js 18+ is installed by running:
node --version
If the command isn’t found or the version is below 18, install Node.js from nodejs.org.
Confirm Git is installed:
git --version
If the command isn’t found, install the Xcode Command Line Tools (xcode-select --install) or download Git from git-scm.com.
Install the StackOne CLI globally via npm:
npm install -g @stackone/cli
The -g flag installs the CLI globally so the stackone command is available in any directory.
Verify the install:
stackone --version

Open Command Prompt or PowerShell from the Start menu.
Confirm Node.js 18+ is installed (node --version). If missing, install from nodejs.org.
Confirm Git is installed (git --version). If missing, install Git for Windows.
Install the StackOne CLI: npm install -g @stackone/cli
Verify with stackone --version.

Open your terminal application.
Confirm Node.js 18+ is installed (node --version). Install via your package manager if needed.
Confirm Git is installed (git --version). If missing, install via your package manager (e.g., sudo apt install git on Debian/Ubuntu, sudo dnf install git on Fedora).
Install the StackOne CLI: npm install -g @stackone/cli
Verify with stackone --version.

Set Up Your Working Directory

Create your own private GitHub repository by following the connectors-template setup guide.Clone your new private repo into a my-connector folder and install dependencies:

git clone https://github.com/<your-org>/<your-repo>.git my-connector
cd my-connector
npm install

All subsequent CLI commands run from inside my-connector.

The template ships with agent skills (including /on-boarding), CI/CD workflows, a pre-configured CLAUDE.md, and example connector structures.

Starting without connectors-template

You can build connectors without the template, but you’ll skip the bundled agent skills (like /on-boarding), pre-configured CLAUDE.md, and CI/CD workflows.

Create an empty folder, move into it, then pull an existing connector as a reference:

mkdir my-connector
cd my-connector
stackone pull --connector provider --output ./connectors/

Configure the StackOne CLI

From inside your working directory, authenticate the StackOne CLI:

# Authenticate globally (stores credentials in ~/.stackone)
stackone agent setup --global

# Or scope to current project only
stackone agent setup --local

This configures MCP tools for AI-assisted development and stores your access token.

Create a StackOne CLI Profile

Create a named profile so deployment commands like stackone push can authenticate without you pasting your API key each time:

stackone init

You’ll be prompted for a profile label and an API key — paste the StackOne API key you generated in Step 1. Create separate profiles for staging vs. production and reference them later with --profile <profile-label>.

Starting the Build

The connectors-template includes agent skills and a pre-configured CLAUDE.md, so the recommended path is to open your project in an AI coding assistant and start a chat from inside the my-connector directory.

Claude Code
Cursor / VS Code

From inside my-connector, launch Claude Code:

claude

The template’s CLAUDE.md and bundled skills (including /on-boarding) load automatically.

Open the my-connector folder in Cursor or VS Code with the Claude extension, then open the AI chat panel.

Once the chat is open, run the onboarding skill:

/on-boarding

This launches an interactive flow that guides you through:

Connector type selection — Agentic Actions (raw provider data) vs Schema-Based (unified output)
Provider details — Name, API version, and pulling any existing connector
Authentication setup — Configuring and validating auth before building actions
Schema definition (for unified connectors) — Defining your target output format
Endpoint research — Discovering available API endpoints and their trade-offs
Action building — Implementing and testing each action

The onboarding flow ensures you complete each step before moving to the next, reducing errors and rework.

Experienced users: Skip onboarding and tell the agent directly what you need:

“Build a connector for [Provider] with employee management actions”
“Start unified build for [Provider]” (for schema-based connectors)

Build Workflow

The recommended workflow ensures you validate each step before moving to the next:

Step 1: Fork or Pull Existing Connector

Always start by checking if a connector already exists:

# Pull existing connector from StackOne registry
stackone pull --connector provider --output ./connectors/

# Check what was downloaded
ls connectors/provider/

If the pull succeeds, you have a foundation to build on. If it fails, create a new connector structure:

connectors/provider/
├── provider.connector.s1.yaml       # Main file (auth, metadata)
└── provider.employees.s1.partial.yaml  # Actions by resource

Step 2: Build Authentication

Do not proceed until authentication works. All other work depends on valid auth.

Configure authentication in the main connector file:

API Key (Bearer)
API Key (Header)
Basic Auth

authentication:
  - custom:
      type: custom
      label: API Key
      authorization:
        type: bearer
        token: $.credentials.apiKey
      configFields:
        - key: apiKey
          label: API Key
          type: password
          required: true
          secret: true
      testActionsIds:
        - list_users  # Simple action to test auth

authentication:
  - custom:
      type: custom
      label: API Key
      authorization:
        type: none
      customHeaders:
        X-API-Key: $.credentials.apiKey
      configFields:
        - key: apiKey
          label: API Key
          type: password
          required: true
          secret: true

authentication:
  - custom:
      type: custom
      label: Basic Auth
      authorization:
        type: basic
        username: $.credentials.username
        password: $.credentials.password
      configFields:
        - key: username
          label: Username
          type: text
          required: true
        - key: password
          label: Password
          type: password
          required: true
          secret: true

Create a simple test action (e.g., list_users) and verify auth works before building more actions.

Step 3: Connect Account & Test Auth

Most providers offer sandbox or developer accounts for testing — check the provider’s developer portal for signup, then generate API credentials (API key, OAuth app, etc.). Note any rate limits or restrictions on sandbox accounts. Create test files for local development:

# Create account config
echo '{"environment": "production", "provider": "provider"}' > account.json

# Create credentials (gitignore this!)
echo '{"apiKey": "your_sandbox_api_key"}' > credentials.json

Keep sandbox credentials separate from production. Store them in a credentials.json file that’s gitignored.

Test authentication:

stackone run \
  --connector connectors/provider/provider.connector.s1.yaml \
  --account account.json \
  --credentials credentials.json \
  --action-id list_users \
  --debug

Alternative: push and link an account

If you prefer, push the connector and create a linked account in the StackOne dashboard (see Getting Started guide). Then use --account-id instead of local credential files:

stackone push connectors/provider/ --profile <profile-label>
# Create the linked account in the dashboard, then:
stackone run \
  --connector connectors/provider/provider.connector.s1.yaml \
  --account-id your-linked-account-id \
  --action-id list_users

<profile-label> is the name you set when running stackone init (see Setup).

Step 4: Build Actions

With auth working, build out your actions. See Common Step Functions for patterns.

Step 5: Iterate

Validate syntax: stackone validate connectors/provider/
Test actions: stackone run --debug ...
Fix issues and repeat

Common Step Functions

`request` - Single HTTP Request

Use for GET single resource, POST create, PUT update operations:

steps:
  - stepId: get_user
    stepFunction:
      functionName: request
      parameters:
        url: /users/${inputs.id}
        method: get
        response:
          collection: false
          dataKey: data.user  # Extract nested response

`paginated_request` - Cursor Pagination

Use for list endpoints with cursor-based pagination:

steps:
  - stepId: list_users
    stepFunction:
      functionName: paginated_request
      parameters:
        url: /users
        method: get
        response:
          dataKey: data.users      # Path to data array
          nextKey: meta.next_cursor # Path to pagination cursor
          indexField: id            # Unique ID field in each record
        iterator:
          key: cursor              # Parameter name API expects
          in: query                # Send cursor as query param
        args:
          - name: limit
            value: "100"
            in: query

Verify paths with --debug before assuming response structure. Common mistake: using dataKey: users when the actual path is dataKey: data.users.

`map_fields` - Transform Data (Unified Connectors)

Transform provider response to your schema:

steps:
  - stepId: map_data
    stepFunction:
      functionName: map_fields
      version: "2"
      parameters:
        dataSource: $.steps.get_users.output.data
        fields:
          - targetFieldKey: id
            expression: $.user_id
            type: string
          - targetFieldKey: email
            expression: $.email_address
            type: string
          - targetFieldKey: full_name
            expression: "{{$.first_name + ' ' + $.last_name}}"
            type: string
          - targetFieldKey: status
            expression: $.account_status
            type: enum
            enumMapper:
              matcher:
                - matchExpression: '{{$.account_status == "ACTIVE"}}'
                  value: active
                - matchExpression: '{{$.account_status == "INACTIVE"}}'
                  value: inactive

Always use version: "2" for map_fields and typecast steps.

`typecast` - Apply Type Conversions

Apply after map_fields to ensure correct types:

steps:
  - stepId: typecast_data
    stepFunction:
      functionName: typecast
      version: "2"
      parameters:
        dataSource: $.steps.map_data.output.data
        fields:
          - targetFieldKey: id
            type: string
          - targetFieldKey: created_at
            type: datetime_string
          - targetFieldKey: is_active
            type: boolean

Cursor Pagination with Dynamic Page Size

For list actions where callers can specify page size, use the dual-condition pattern:

inputs:
  - name: page_size
    type: number
    in: query
    required: false
    description: Results per page (max 100)
  - name: cursor
    type: string
    in: query
    required: false
    description: Pagination cursor

cursor:
  enabled: true
  pageSize: 50

steps:
  - stepId: get_data
    stepFunction:
      functionName: request
      parameters:
        url: /items
        method: get
        args:
          # Use page_size if provided
          - name: limit
            value: $.inputs.page_size
            in: query
            condition: "{{present(inputs.page_size)}}"
          # Otherwise use default
          - name: limit
            value: 50
            in: query
            condition: "{{!present(inputs.page_size)}}"
          # Pass cursor when present
          - name: cursor
            value: $.inputs.cursor
            in: query
            condition: "{{present(inputs.cursor)}}"

result:
  data: $.steps.get_data.output.data.items
  next: $.steps.get_data.output.data.meta.next_cursor

StackOne CLI Examples

For the full command list, see the CLI Reference. The examples below cover the patterns you’ll use most while iterating on your first connector.

Validate as you build

Watch mode re-runs validation on every save:

stackone validate connectors/provider/ --watch

Test actions with parameters

--params accepts a structured JSON object with these top-level keys, each corresponding to an input’s in: location in the action’s YAML:

path — in: path inputs (URL path parameters)
queryParams — in: query inputs
header — in: headers inputs (note: singular header)
body — in: body inputs

Place every value under the key that matches the input’s in: location:

stackone run \
  --connector connectors/provider/provider.connector.s1.yaml \
  --account-id linked-account-id \
  --action-id get_employee \
  --params '{"path": {"id": "emp_123"}, "queryParams": {"include": "manager"}}'

Push when ready

stackone push connectors/provider/ --profile <profile-label>

<profile-label> is the name you set when running stackone init (see the setup section). Create separate profiles for staging vs. production and swap the label as needed.

Debugging

Enable Debug Mode

Add --debug to any stackone run command to surface:

The raw HTTP request sent to the provider (URL, method, headers, body)
The full response body before any mapping is applied
The inputs and outputs of each step in the connector
The resolved values of any JSONPath or JEXL expressions

stackone run \
  --connector connectors/provider/provider.connector.s1.yaml \
  --account-id linked-account-id \
  --action-id list_employees \
  --debug

Debug Empty or Incorrect Results

When mapping produces unexpected results:

Test raw response first

Temporarily modify your result block to return raw data:

result:
  data: $.steps.get_employees.output.data  # Raw, before map_fields

Verify response structure

Run with --debug and examine the actual paths:

stackone run --debug ... | jq '.steps.get_employees.output'

Add fields incrementally

Start with one field in map_fields, verify it works, then add more.

Check expression context

For inline fields in map_fields, expressions reference fields directly ($.email), not with step prefix ($.get_employees.email).

Common Issues

Symptom	Likely Cause	Fix
401 Unauthorized	Invalid credentials	Check API key, regenerate if needed
Empty data array	Wrong `dataKey` path	Use `--debug` to verify actual response structure
Null field values	Incorrect expression path	Verify nested paths match actual response
Pagination returns same data	Wrong `iterator.key`	Check API docs for expected cursor parameter name
Enum not translated	`matchExpression` case mismatch	Provider might return `"ACTIVE"` not `"Active"`

Error Mapping

Map provider-specific errors to meaningful responses using error handlers:

errorHandlers:
  - condition: '{{response.status == 404}}'
    message: "Resource not found"
    code: NOT_FOUND
  - condition: '{{response.status == 429}}'
    message: "Rate limit exceeded. Retry after {{response.headers.retry-after}} seconds"
    code: RATE_LIMITED
  - condition: '{{response.status == 403}}'
    message: "Insufficient permissions for this operation"
    code: FORBIDDEN

For unified connectors, map provider error codes to standard error responses:

errorHandlers:
  - condition: '{{response.body.error.code == "INVALID_TOKEN"}}'
    message: "Authentication failed - token may be expired"
    code: UNAUTHORIZED
  - condition: '{{response.body.error.code == "MISSING_SCOPE"}}'
    message: "Missing required permission: {{response.body.error.required_scope}}"
    code: FORBIDDEN

Manual Testing Methods

Beyond stackone run, you have additional testing options:

Action Request Tester (Dashboard)

The StackOne dashboard includes an Action Request Tester for testing deployed connectors:

Navigate to your project in the dashboard
Select a linked account
Choose an action and provide parameters
Execute and view results

This tests the deployed connector version against real credentials.

RPC Calls via API

Test actions programmatically using the StackOne API:

curl -X POST "https://api.stackone.com/unified/actions/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-account-id: your-linked-account-id" \
  -d '{
    "action_id": "provider_list_employees",
    "params": {
      "page_size": 10
    }
  }'

Actions only appear in the Request Tester if they’re enabled in your connector profile. If you don’t see an action, edit your connector profile and enable it.

MCP Testing (AI Agents)

If using Claude Code or similar, test actions conversationally:

Test the list_employees action for the provider connector.
Use page_size of 5 and verify the response includes id, name, and email fields.

The AI agent will execute the action and validate results.

Unified Connector Checklist

For schema-based connectors, verify:

Schema Definition

Target schema documented before building
All required fields identified
Field types specified (string, number, enum, datetime_string)
Enum values defined with mappings

Field Mapping

fieldConfigs map all schema fields
targetFieldKey uses YOUR schema names (not provider names)
Nested paths verified against actual response
Enum mappings handle all provider values + default case

Pagination

cursor.enabled: true for list actions
dataKey path verified with --debug
nextKey path verified with --debug
result.next returns cursor for next page
Tested: first page, next page, last page, empty results

Steps

map_fields step with version: "2"
typecast step with version: "2"
Correct dataSource references between steps

Optimizing Agent Performance

The connector building agent starts with baseline capabilities. As you build connectors, you can improve agent performance by creating custom skills that encode your specific use cases and schemas.

The Optimization Workflow

Why Create Custom Skills?

Without Skills	With Skills
Agent asks for schema every time	Agent auto-loads your schema skill
Generic action structures	Actions match your specific requirements
Manual field mapping decisions	Consistent mapping patterns across connectors
Repeated explanations of your use case	Agent understands context immediately

Creating Schema Skills

After building your first few connectors, extract your schema into a reusable skill:

.claude/skills/schemas/
└── my-use-case-schema.md

Example schema skill:

---
name: Employee Sync Schema
description: Target schema for employee data synchronization
category: hris
---

# Employee Sync Schema

## Target Schema

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| id | string | yes | Unique identifier |
| email | string | yes | Primary email |
| first_name | string | yes | |
| last_name | string | yes | |
| status | enum | yes | Values: active, inactive, terminated |
| department | string | no | |
| hire_date | datetime_string | no | ISO 8601 format |

## Enum Mappings

### status
| Provider Value | Schema Value |
|----------------|--------------|
| Active, active, ACTIVE | active |
| Inactive, inactive, INACTIVE | inactive |
| Terminated, terminated, TERMINATED | terminated |
| * (default) | unknown |

Once created, the agent automatically uses this schema for future unified builds — no questions needed.

Recommended Progression

Build 2-3 Connectors

Use the baseline agent to build your first connectors. Note patterns in your requirements.

Create Schema Skills

Extract your target schemas into .claude/skills/schemas/. Include field definitions, types, and enum mappings.

Document Use-Case Patterns

Create skills that describe your specific integration patterns, endpoint preferences, or data transformation rules.

Iterate and Refine

As you build more connectors, update skills based on edge cases and lessons learned.

Skills are stored in .claude/skills/ in the connectors-template repository. The agent reads these automatically when relevant to the current task.

Next Steps

Connector Structure

Detailed YAML structure reference

Expression Language

JSONPath, JEXL, and string interpolation

YAML Reference

Complete property documentation

CI/CD Setup

Automated deployment with GitHub Actions

​Setup

​Starting the Build

​Build Workflow

​Step 1: Fork or Pull Existing Connector

​Step 2: Build Authentication

​Step 3: Connect Account & Test Auth

​Step 4: Build Actions

​Step 5: Iterate

​Common Step Functions

​request - Single HTTP Request

​paginated_request - Cursor Pagination

​map_fields - Transform Data (Unified Connectors)

​typecast - Apply Type Conversions

​Cursor Pagination with Dynamic Page Size

​StackOne CLI Examples

​Validate as you build

​Test actions with parameters

​Push when ready

​Debugging

​Enable Debug Mode

​Debug Empty or Incorrect Results

​Common Issues

​Error Mapping

​Manual Testing Methods

​Action Request Tester (Dashboard)

​RPC Calls via API

​MCP Testing (AI Agents)

​Unified Connector Checklist

​Optimizing Agent Performance

​The Optimization Workflow

​Why Create Custom Skills?

​Creating Schema Skills

​Recommended Progression

​Next Steps

Connector Structure

Expression Language

YAML Reference

CI/CD Setup

Setup

Starting the Build

Build Workflow

Step 1: Fork or Pull Existing Connector

Step 2: Build Authentication

Step 3: Connect Account & Test Auth

Step 4: Build Actions

Step 5: Iterate

Common Step Functions

`request` - Single HTTP Request

`paginated_request` - Cursor Pagination

`map_fields` - Transform Data (Unified Connectors)

`typecast` - Apply Type Conversions

Cursor Pagination with Dynamic Page Size

StackOne CLI Examples

Validate as you build

Test actions with parameters

Push when ready

Debugging

Enable Debug Mode

Debug Empty or Incorrect Results

Common Issues

Error Mapping

Manual Testing Methods

Action Request Tester (Dashboard)

RPC Calls via API

MCP Testing (AI Agents)

Unified Connector Checklist

Optimizing Agent Performance

The Optimization Workflow

Why Create Custom Skills?

Creating Schema Skills

Recommended Progression

Next Steps