Build Workflow - Stackone

Building a connector is a loop, and the order matters: every action you write depends on authentication already working. Validate each stage before moving to the next. This assumes you’ve already got the CLI installed and authenticated.

Pull existing or create

Always check whether a connector already exists before writing one, since starting from the registry gives you a working foundation. Files save to ./connectors/[provider]/ by default:

stackone pull --connector [provider] --profile [profile-label]
ls connectors/[provider]/

If nothing exists to pull, the agent writes the files for you, laid out as described in File Structure.

Build authentication

Don’t move on until authentication works. Everything else depends on it.

Configure authentication in the main connector file. The common patterns:

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 authentication

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

Add one simple action — a list_users or equivalent — and use it to prove authentication works before building anything else.

Connect an account

Most providers offer sandbox or developer accounts. Check the provider’s developer portal to sign up and generate credentials, and note any rate limits or restrictions that apply to sandbox access. For local development, keep the account config and credentials in separate files:

echo '{"environment": "production", "provider": "[provider]"}' > account.json
echo '{"apiKey": "your_sandbox_api_key"}' > credentials.json

Add credentials.json to .gitignore. Keep sandbox credentials separate from production ones.

Then run your test action against those files:

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 instead

Rather than local credential files, you can push the connector and link an account in the dashboard, then run against that account by ID:

stackone push connectors/[provider]/ --profile [profile]
# link the account in the dashboard, then:
stackone run \
  --connector connectors/[provider]/[provider].connector.s1.yaml \
  --account-id [account-id] \
  --action-id list_users

[profile] is the name you set with stackone init.A pushed connector appears in the dashboard alongside the StackOne ones, so linking an account against it is the same flow as any other connector: create a connector profile, then link an account. Other linking methods are covered in Linking Accounts.

Build actions and iterate

With authentication proven, add your remaining actions to the resource partials. Each action is built from step functions. Then cycle: validate the syntax, run the action with --debug, fix, repeat. If the actions should return a normalized shape rather than the provider’s own, see Defined Output Schemas.

stackone validate connectors/[provider]/ --watch

Running validate with --watch keeps checking as you edit, so you catch schema mistakes without rerunning by hand.

The Playground also runs your connector’s actions in natural language, which is handy for a quick check without the CLI.

Debugging

Add --debug to any stackone run 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
The resolved values of any JSONPath or JEXL expressions

Empty or incorrect results

When mapping produces something unexpected, work backwards from the raw response:

Check the raw response first

Temporarily return the unmapped data so you can see what the provider actually sent:

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

Verify the response structure

Run with --debug and inspect the real paths:

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

Add fields one at a time

Start with a single field in map_fields, confirm it resolves, then add the rest.

Check the expression context

Inline fields in map_fields reference the field directly ($.email), not via the step ($.get_employees.email).

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

Publish

When the connector behaves, push it to your project’s registry so linked accounts can use it:

stackone push connectors/[provider]/ --profile [profile]

For team workflows, connectors are usually published through a Git pipeline rather than a direct push. See GitHub CI/CD.

Connector Versioning

Release new versions without breaking existing linked accounts.

Other ways to test

Once it’s published, stackone run is no longer the only way in. Each of these exercises the deployed version against a linked account’s real credentials, so they need a connector profile and a linked account first:

Surface	Use it to
Request Tester	Pick an action in the dashboard, fill in parameters, and inspect the response
`POST /actions/rpc`	Call the action the way your own backend will
Playground	Check an agent picks the right action from your descriptions

An action only shows up on these surfaces once it’s enabled on the connector profile.

Next steps

Defined Output Schemas

Map provider responses onto a schema of your own.

Step Functions

The building blocks each action is made of.

StackOne CLI

Full command reference for pull, validate, run, and push.

Implementing Events

Define the events your connector emits.

​Pull existing or create

​Build authentication

​Connect an account

​Build actions and iterate

​Debugging

​Publish

Connector Versioning

​Other ways to test

​Next steps

Defined Output Schemas

Step Functions

StackOne CLI

Implementing Events

Pull existing or create

Build authentication

Connect an account

Build actions and iterate

Debugging

Publish

Other ways to test

Next steps