> ## 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. # Connector Versioning > Connector versioning ensures your linked accounts aren't affected by breaking changes until you're ready to adopt them. Pin each connector profile to a version and upgrade on your own schedule. 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: 1. The latest **custom** version of the connector, if one exists in your project. 2. Otherwise, the latest **StackOne** version. Custom connectors are connectors you build and publish yourself using the [Falcon framework](/guides/connector-engine/overview). 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: ```bash theme={null} curl -X PUT https://api.stackone.com/connector_profiles/{connector_profile_id}/pinned_version \ -H "Authorization: Basic " \ -H "Content-Type: application/json" \ -d '{"pinned_version": "1.x.x"}' ``` To revert to the default resolution (custom latest, then StackOne latest): ```bash theme={null} curl -X DELETE https://api.stackone.com/connector_profiles/{connector_profile_id}/pinned_version \ -H "Authorization: Basic " ``` 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: ```bash theme={null} curl https://api.stackone.com/connector_profiles/{connector_profile_id}/versions \ -H "Authorization: Basic " ``` ```json theme={null} [ { "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: ```bash theme={null} curl -X PUT https://api.stackone.com/connector_profiles/{connector_profile_id}/pinned_version \ -H "Authorization: Basic " \ -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. The existing connector profile and all accounts on it are untouched. This new profile handles the updated auth flow. Call [`GET /connector_profiles`](/platform/api-reference/connector-profiles/list-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.) 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](/platform/connect-your-backend-with-stackone#targeting-a-specific-connector-profile) for the request format. 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. 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**. 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](/guides/connector-engine/cli-reference) `--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.