Connect your Backend with StackOne

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. `jane@company.com`)
`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

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');
  }
});

from flask import Flask, request, jsonify
import requests
import base64

app = Flask(__name__)

@app.route('/stackone_connect_sessions', methods=['POST'])
def stackone_connect_sessions():
    STACKONE_API_KEY = 'YOUR_STACKONE_API_KEY'
    headers = {
        'Authorization': 'Basic ' + base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode(),
        'Content-Type': 'application/json',
    }
    req_data = request.json

    payload = {
        'origin_owner_id': 'customer-123',
        'origin_owner_name': 'Acme Inc',
        'origin_username': req_data.get('originUsername'),
        'provider': req_data.get('provider'),
    }

    try:
        response = requests.post(
            'https://api.stackone.com/connect_sessions',
            headers=headers,
            json=payload
        )
        token = response.json().get('token')
        return jsonify({'token': token})
    except Exception as e:
        return ('error when trying to fetch session', 500)

using Newtonsoft.Json;
using Microsoft.AspNetCore.Mvc;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

[ApiController]
[Route("[controller]")]
public class StackOneConnectSessionsController : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> Post([FromBody] dynamic reqBody)
    {
        string STACKONE_API_KEY = "YOUR_STACKONE_API_KEY";
        string authHeader = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{STACKONE_API_KEY}:"));

        HttpClient client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", $"Basic {authHeader}");

        dynamic payload = new
        {
            origin_owner_id = "customer-123",
            origin_owner_name = "Acme Inc",
            origin_username = reqBody.originUsername,
            provider = reqBody.provider,
        };

        try
        {
            var response = await client.PostAsync(
                "https://api.stackone.com/connect_sessions",
                new StringContent(JsonConvert.SerializeObject(payload), Encoding.UTF8, "application/json")
            );
            dynamic data = JsonConvert.DeserializeObject(await response.Content.ReadAsStringAsync());
            return Ok(new { token = data.token });
        }
        catch (Exception)
        {
            return StatusCode(500, "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.

Getting Started

Common Use-Cases

API Behavior

Endpoints

Connect your Backend with StackOne

Required fields

Optional fields

Basic implementation

Account behavior

Multiple accounts for the same provider

Targeting a specific connector profile

Customizing the Hub Behavior

​Required fields

​Optional fields

​Basic implementation

​Account behavior

​Multiple accounts for the same provider

​Targeting a specific connector profile

​Customizing the Hub Behavior

Required fields

Optional fields

Basic implementation

Account behavior

Multiple accounts for the same provider

Targeting a specific connector profile

Customizing the Hub Behavior