Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stackone.com/llms.txt

Use this file to discover all available pages before exploring further.

Connectors are versioned with semver (major.minor.patch). Each auth config resolves to a specific connector version when linked accounts make requests. This page covers how connector versions are resolved for auth configs, what qualifies as a breaking change, and how immutable versioning protects pinned accounts.

​
Version selection

By default, an auth config resolves to:
  1. The latest custom version of the connector, if one exists in your project.
  2. Otherwise, the latest StackOne version.
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 an auth config, 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.

​
Breaking changes and version updates

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 auth config is pinned to “latest”. Accounts pinned to a specific version remain on that version until the pin is manually updated. Any change that is not backwards compatible should be 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 bumpExample changeBreaking for consumers
Patch (1.2.3 → 1.2.4)Bug fix, description update, internal refactorNo
Minor (1.2.3 → 1.3.0)New action, new optional parameter, new optional response fieldNo
Major (1.2.3 → 2.0.0)New auth type or required scope, removed/renamed field, changed response shape, removed actionYes
Use a major version bump for any breaking change, not just authentication changes. Releasing breaking changes as a minor or patch could silently break existing linked accounts and API consumers.

​
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.
Immutable Versioning toggle enabled in the Danger Zone tab of 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.