Multi-Tenant Account Management

When building on top of StackOne, you need to manage accounts across multiple owners. The origin_owner_id field is your key to segmenting accounts by owner.

This guide is for platform builders creating multi-tenant applications where each owner has their own set of linked accounts.

When you onboard end-users through Connect Sessions, you provide an origin_owner_id that identifies the owner in your system. This ID lets you query accounts for specific owners.

List Accounts by Owner

Use the GET /accounts endpoint with the origin_owner_id query parameter to filter accounts for a specific owner.

TypeScript SDK
cURL
Python

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

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

const { linkedAccounts } = await stackOne.accounts.listLinkedAccounts({
  originOwnerId: "owner_123",
});

// linkedAccounts = [
//   { id: "acct_abc", provider: "bamboohr", status: "active", ... },
//   { id: "acct_def", provider: "salesforce", status: "active", ... }
// ]

curl "https://api.stackone.com/accounts?origin_owner_id=owner_123" \
  -u "$STACKONE_API_KEY:"

import requests
import base64

api_key = "v1.eu1.xxxxx"
headers = {
    "Authorization": f"Basic {base64.b64encode(f'{api_key}:'.encode()).decode()}"
}

response = requests.get(
    "https://api.stackone.com/accounts",
    params={"origin_owner_id": "owner_123"},
    headers=headers
)

accounts = response.json()["data"]

Response

{
  "data": [
    {
      "id": "acct_abc123",
      "origin_owner_id": "owner_123",
      "origin_owner_name": "Acme Corp",
      "provider": "bamboohr",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "acct_def456",
      "origin_owner_id": "owner_123",
      "origin_owner_name": "Acme Corp",
      "provider": "salesforce",
      "status": "active",
      "created_at": "2024-01-20T14:45:00Z"
    }
  ]
}

Filter by Status and Provider

Combine filters to narrow down results:

# Active accounts for an owner with a specific provider
curl "https://api.stackone.com/accounts?origin_owner_id=owner_123&provider=bamboohr&status=active" \
  -u "$STACKONE_API_KEY:"

Available Filters

Parameter	Description
`origin_owner_id`	The owner’s unique identifier
`provider`	Filter by integration provider (e.g., `bamboohr`, `salesforce`)
`status`	Filter by status: `active`, `inactive`, `error`

Building an Owner Dashboard

Here’s how to build a dashboard showing each owner’s integrations:

TypeScript SDK
Python

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

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

async function getOwnerIntegrations(ownerId: string) {
  const { linkedAccounts } = await stackOne.accounts.listLinkedAccounts({
    originOwnerId: ownerId,
  });
  return linkedAccounts ?? [];
}

// Group by provider for display
function groupByProvider(accounts: typeof linkedAccounts) {
  const grouped: Record<string, typeof accounts> = {};
  for (const account of accounts ?? []) {
    const provider = account.provider ?? "unknown";
    grouped[provider] = grouped[provider] || [];
    grouped[provider].push(account);
  }
  return grouped;
}

from collections import defaultdict
import requests
import base64
import os

def get_owner_integrations(owner_id: str) -> list[dict]:
    api_key = os.environ["STACKONE_API_KEY"]
    headers = {
        "Authorization": f"Basic {base64.b64encode(f'{api_key}:'.encode()).decode()}"
    }

    response = requests.get(
        "https://api.stackone.com/accounts",
        params={"origin_owner_id": owner_id},
        headers=headers
    )
    return response.json()["data"]

def group_by_provider(accounts: list[dict]) -> dict[str, list[dict]]:
    grouped = defaultdict(list)
    for account in accounts:
        grouped[account.get("provider", "unknown")].append(account)
    return dict(grouped)

Monitor Account Health

Track the health of your owners’ integrations:

async function getAccountHealthSummary(ownerId: string) {
  const accounts = await getOwnerIntegrations(ownerId);

  return {
    total: accounts.length,
    active: accounts.filter(a => a.status === "active").length,
    needsAttention: accounts.filter(a =>
      ["error", "inactive"].includes(a.status ?? "")
    ).length,
    byProvider: accounts.reduce((acc, a) => {
      acc[a.provider ?? "unknown"] = a.status ?? "unknown";
      return acc;
    }, {} as Record<string, string>)
  };
}

Webhooks for Account Changes

Subscribe to account lifecycle events to keep your system in sync:

Event	Description
`account.created`	New account linked
`account.updated`	Account credentials refreshed
`account.deleted`	Account disconnected
`account.error`	Connection error occurred

Webhooks Guide

Configure webhooks to receive real-time account updates

List Accounts API

Full API reference for listing accounts

Connect Sessions

Onboard end-users with origin_owner_id

Accounts Dashboard

Manage accounts in the StackOne dashboard

Actions Metadata

Build custom UIs with available actions

Getting Started

Common Use-Cases

API Behavior

Endpoints

Multi-Tenant Account Management

List Accounts by Owner

Response

Filter by Status and Provider

Available Filters

Building an Owner Dashboard

Monitor Account Health

Webhooks for Account Changes

Webhooks Guide

List Accounts API

Connect Sessions

Accounts Dashboard

Actions Metadata

​List Accounts by Owner

​Response

​Filter by Status and Provider

​Available Filters

​Building an Owner Dashboard

​Monitor Account Health

​Webhooks for Account Changes

Webhooks Guide

​Related

List Accounts API

Connect Sessions

Accounts Dashboard

Actions Metadata

List Accounts by Owner

Response

Filter by Status and Provider

Available Filters

Building an Owner Dashboard

Monitor Account Health

Webhooks for Account Changes

Related