Connector Versioning

Connectors are versioned with semver (major.minor.patch). Each connector profile resolves to a specific connector version when linked accounts make requests. Because each connector profile pins independently, you can test a new version against a staging profile before rolling it out to production, and migrate different customer groups to a new connector version at their own pace.

Version selection

By default, a connector profile resolves to:

The latest custom version of the connector, if one exists in your project.
Otherwise, the latest StackOne version.

Custom connectors are connectors you build and publish yourself using the Falcon framework. If you only use StackOne’s built-in connectors, item 1 never applies — all requests resolve to item 2. Custom connectors always take precedence over StackOne connectors with the same key, including when version numbers match. Publishing a new StackOne version does not override a custom connector with the same key.

Pinning a version

When creating or editing a connector profile, you can override the default and pin the version to:

Latest StackOne - always resolves to the latest published StackOne version, ignoring custom versions. Use this when you rely on StackOne’s managed updates.
Latest custom - always resolves to the latest published custom version. Use this when you maintain your own connector and want deploys to roll out automatically.
A specific version - pin to an exact version number (StackOne or custom). Use this in production when you need full control over when updates apply.

When pinned to a “latest” option, existing linked accounts automatically pick up new versions as they are published. When pinned to a specific version, linked accounts stay on that version until the pin is changed. The accepted pin formats are:

Pin	Resolves to	Auto-updates
`latest`	Newest version (custom if exists, else StackOne)	Yes
`1.x.x`	Latest minor + patch within major version 1	Yes, within major 1
`1.2.x`	Latest patch within 1.2.*	Yes, patch only
`1.2.0`	Exactly 1.2.0, never changes	No
(no pin)	Custom latest if exists, else StackOne latest	Yes

Note: npm-style caret (^1.2.0) and tilde (~1.2) are not accepted. You can set the pin when editing a connector profile in the dashboard, or via the API:

curl -X PUT https://api.stackone.com/connector_profiles/{connector_profile_id}/pinned_version \
  -H "Authorization: Basic <base64(api_key:)>" \
  -H "Content-Type: application/json" \
  -d '{"pinned_version": "1.x.x"}'

To revert to the default resolution (custom latest, then StackOne latest):

curl -X DELETE https://api.stackone.com/connector_profiles/{connector_profile_id}/pinned_version \
  -H "Authorization: Basic <base64(api_key:)>"

Pin production connector profiles to a major version wildcard — for example 1.x.x rather than latest. A new major version can include auth or scope changes that break existing linked accounts if they upgrade without warning. With 1.x.x, you pick up bug fixes and new optional fields automatically while keeping control over breaking upgrades.

Breaking changes and version updates

This is how StackOne classifies changes when versioning its built-in connectors. Understanding these categories helps you interpret what a version bump means and whether it requires action on your end. Publishing a new connector version does not invalidate existing linked accounts. Accounts continue to work and automatically pick up the new version on the next request, provided the connector profile is on an auto-updating pin (latest, 1.x.x, or 1.2.x). Accounts pinned to a specific version remain on that version until the pin is manually updated. Any change that is not backwards compatible is released as a new major version. This includes, but is not limited to:

Authentication changes - switching auth type, adding required scopes, or changing required credential fields. These require linked accounts to re-authenticate.
Response shape changes - renaming or removing fields, changing field types, or restructuring nested objects in an action’s response.
Request shape changes - renaming or removing parameters, making optional parameters required, or changing accepted value types.
Removed or renamed actions - any action that callers may currently reference.
Behavioural changes - changes to pagination, filtering, error semantics, or default values that consumers may have relied on.

Version bump	Example change	Breaking for consumers
Patch (`1.2.3 → 1.2.4`)	Bug fix, description update, internal refactor	No
Minor (`1.2.3 → 1.3.0`)	New action, new optional parameter, new optional response field	No
Major (`1.2.3 → 2.0.0`)	New auth type or required scope, removed/renamed field, changed response shape, removed action	Yes

Versioning strategy

When building custom connectors, you set your own versioning convention. The version number communicates what kind of migration work a change requires for anyone pinned to it. Auth-breaking changes — new OAuth flow, required scopes, or changed credential fields — require end users to reauthenticate. These almost always warrant a major version bump. The migration involves creating a new connector profile and prompting users through a new connect flow. A common approach:

Level	Use for	Who needs to act
Major	Auth flow or scope changes	Your end users — they reauthenticate through the new flow
Minor	New actions, new optional fields or parameters	Nobody — existing code keeps working
Patch	Bug fixes, internal refactors	Nobody — existing code keeps working

The version level is your contract with yourself — pick the convention that makes your migration work predictable.

Checking available versions

To see every published version for a connector profile and which one is currently active:

curl https://api.stackone.com/connector_profiles/{connector_profile_id}/versions \
  -H "Authorization: Basic <base64(api_key:)>"

[
  {
    "version": "1.0.0",
    "pinned": false,
    "builtin": true,
    "owner": "stackone"
  },
  {
    "version": "1.2.0",
    "pinned": true,
    "builtin": true,
    "owner": "stackone"
  }
]

The pinned: true entry is the version currently serving requests for this connector profile. Note that the response shows the resolved exact version (1.2.0), not the pin format (1.2.x) — the pin itself is set on the connector profile, not returned here.

Migrating to a new version

Non-breaking releases

For releases your team has classified as non-breaking (patch fixes, new optional fields, additive changes), connector profiles pinned to latest, a major wildcard (1.x.x), or a minor wildcard (1.2.x) will pick up the new version automatically on the next request — no action required. If your connector profile is pinned to an exact version (e.g. 1.2.0), it won’t move until you update the pin manually:

curl -X PUT https://api.stackone.com/connector_profiles/{connector_profile_id}/pinned_version \
  -H "Authorization: Basic <base64(api_key:)>" \
  -H "Content-Type: application/json" \
  -d '{"pinned_version": "1.2.1"}'

Auth/permissions breaking changes

When a connector introduces a new OAuth flow or required scope, existing accounts stay on their current connector profile until you explicitly migrate them. This is a coordinated rollout rather than a silent upgrade.

Create a new connector profile pinned to the new major version

The existing connector profile and all accounts on it are untouched. This new profile handles the updated auth flow.

Get the connector_profile_id for the new connector profile

Call GET /connector_profiles and read the id of the profile you created. Pass that value as connector_profile_id when creating connect sessions. (integration_id is a deprecated alias for the same field in some payloads.)

Issue connect session tokens for the new connector profile

Pass connector_profile_id explicitly when creating connect sessions — this routes the session to the new profile. Alternatively, make the new connector profile the project default and omit connector_profile_id.See Using connect sessions with specific connector profiles for the request format.

Prompt end users to reauthenticate

Send an email, in-app notification, or modal prompting users to reconnect through the Integration Hub. The connect flow uses the new session token, which routes to the new connector profile. You can identify which accounts still need migration by checking which remain associated with the old connector profile.

Accounts migrate on successful auth

When a user completes the new auth flow, their linked account moves to the new connector profile. Subsequent requests resolve against the new major version.

The recommended migration pattern is a staging connector profile pinned to the new version. Test your integration against it before updating the production profile. Each connector profile pins independently, so there’s no coupling between environments.

Immutable versioning

Immutable versioning controls whether published versions can be overwritten. It is enabled by default and toggled from the Danger Zone tab in Project Settings.

Enabled (default) - Each version number is locked once published. Subsequent publishes must use a new version number. Use this to guarantee that linked accounts on a pinned version see exactly the connector that was originally published.
Disabled - Republishing the same version number is allowed when pushing with the CLI’s --force flag (stackone push --force). Without --force, the CLI still rejects overwrites. Linked accounts resolving to an overwritten version will pick up the new content on the next request.

When immutable versioning is enabled, the --force flag has no effect - overwrites are rejected regardless.

Enable immutable versioning in production projects to prevent accidental overwrites of a version that linked accounts depend on. Disable it in development projects where iterating on a version without bumping the number is convenient.

Documentation Index

​Version selection

​Pinning a version

​Breaking changes and version updates

​Versioning strategy

​Checking available versions

​Migrating to a new version

​Non-breaking releases

​Auth/permissions breaking changes

​Immutable versioning

Version selection

Pinning a version

Breaking changes and version updates

Versioning strategy

Checking available versions

Migrating to a new version

Non-breaking releases

Auth/permissions breaking changes

Immutable versioning