Connect your Backend with StackOne

Generate connect session tokens from your backend to securely link customer accounts through the Integration Hub

Connect sessions are short-lived tokens your backend generates to open the Integration Hub for a specific end user. Because they’re generated server-side using your API key, your key is never exposed to the frontend.

You’ll need a StackOne API key to call the Connect Sessions endpoint.

Required fields

Field	Description
origin_owner_id	The ID of the organization in your system (e.g. your customer’s org ID)
origin_owner_name	A human-readable name for the organization, stored against the account in StackOne

These two fields combined with provider determine whether a new account is created or an existing one is updated. If the same combination has been used before, the existing account opens in edit mode. If not, a new account is created.

Always set origin_owner_id server-side. Never pass it through from a client-side request.

Optional fields

Field	Description
origin_username	Identifier for the user initiating the connection (e.g. [e-mail])
provider	Opens the Hub directly at the credential entry step for this provider. Without it, the Hub shows the full provider selection screen.
categories	Array of category keys to open the Hub at the category selection step (e.g. ["hris", "ats"]). Use when you want the user to pick a provider themselves.
account_id	If an existing account ID is passed, the Hub opens in edit mode for that account so credentials can be updated.
connector_profile_id	Routes the session to a specific connector profile. Use this to target a non-default connector profile, for example after a connector major version upgrade. integration_id is deprecated but still accepted as an alias for the same value.
label	Arbitrary string stored against the account.
multiple	Set to true to create a new account even when an existing one with the same origin_owner_id and origin_owner_name exists for this provider.

If no connector_profile_id is passed, the connect session is created against the default connector profile for the given provider. You can set the default connector profile from the Connector Profiles page.

provider_version is deprecated. Passing it no longer selects a connector version and can cause session creation to fail. Remove it from your requests. To target a specific connector profile, use connector_profile_id instead.

Basic implementation

JavaScript

import { StackOne } from "@stackone/stackone-client-ts";

const stackOne = new StackOne({
  security: {
    username: process.env.STACKONE_API_KEY,
    password: "",
  },
});

app.post('/stackone_connect_sessions', async (req, res) => {
  const { originUsername, provider } = req.body;

  try {
    const result = await stackOne.connectSessions.createConnectSession({
      originOwnerId: "customer-123",
      originOwnerName: "Acme Inc",
      originUsername: originUsername,
      provider,
    });

    res.send({ token: result.connectSessionTokenAuthLink?.token });
  } catch (e) {
    res.status(500).send('error when trying to fetch session');
  }
});

Account behavior

origin_owner_id + origin_owner_name + provider seen before?	Result
No	New account created
Yes	Existing account opened in edit mode
— with account_id	That specific account opened in edit mode
— with multiple: true (no account_id)	New account created regardless of existing ones

Multiple accounts for the same provider

By default, creating a connect session with an origin_owner_id and origin_owner_name combination that already exists for a given provider will open that existing account in edit mode rather than create a new one.

If you need multiple linked accounts for the same provider under the same origin_owner_id — for example if a single customer connects several separate instances of the same tool — pass multiple: true. This creates a new account each time regardless of any existing ones with matching details.

multiple has no effect when account_id is set. When account_id is present the session always opens that specific account in edit mode.

Targeting a specific connector profile

Passing provider alone creates a session using the project’s default connector profile for that provider. This is the right choice for most cases — if you only have one profile per provider, or want users going through the standard flow, you don’t need anything else.

Each connector profile has a version pin controlling which connector version its linked accounts use. When you issue a connect session, the linked account that results from it is tied to the profile the session was created against — and inherits that profile’s version pin. This is how connector version migration works in practice: you create a new connector profile pinned to the new version, then issue connect sessions with that profile’s connector_profile_id so users authenticate against the new profile. When they reconnect, their account moves to the new version.

To route a session to a specific connector profile — for example when you have multiple profiles for the same provider, or you’re migrating end users to a new connector version — pass its connector_profile_id.

Get the ID by calling GET /connector_profiles and using the id field from the connector profile you want to target:

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

Then pass it in the session request:

curl -X POST https://api.stackone.com/connect_sessions \
  -H "Authorization: Basic <base64(api_key:)>" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_owner_id": "customer-123",
    "origin_owner_name": "Acme Inc",
    "provider": "bamboohr",
    "connector_profile_id": "01JHMM0V..."
  }'

This is most commonly used when migrating end users to a new connector major version that requires reauthentication. See Connector Version Management for the full migration flow.

Customizing the Hub Behavior