Multi-Tenant Accounts

You serve your end-users, and each of them connects their own provider account — which becomes a linked account you call against. One StackOne setup can serve many customers, and the origin_owner_id field is your key to segmenting accounts by owner.

How customers stay isolated

Linked accounts keep each customer’s credentials separate. You target a specific account when making a request, so one customer’s data never crosses into another’s.
Connector profiles define the connectors and auth available to your customers. You can run multiple profiles per connector — for example, your own OAuth app for some customers and API-key auth for others.
Projects isolate at a higher level. Use separate projects when customers need different regions, environments, or API keys.

Identifying the client on each account

Every linked account carries the origin owner fields set when the account is linked — whether through the dashboard’s Link Account flow, the Hub, or a connect session:

Origin Owner ID (origin_owner_id) — your identifier for the client’s organization. This is how StackOne knows which of your clients an account belongs to.
Origin Owner Name (origin_owner_name) — a human-readable name stored against the account, used across the dashboard (for example, the Account filter in Request Logs).
Origin Username (origin_username, optional) — the end-user’s username, e.g. an email address.

The origin_owner_id + origin_owner_name + provider combination decides whether linking creates a new account or updates an existing one — see New or existing account.

Provisioning at scale

Onboarding a new customer doesn’t require manual setup per account. Configure each connector once in the project, and new customers link themselves against it.

For account-region requirements or a setup serving many customers, talk to your StackOne account manager about the right project structure.

List accounts by owner

Use the GET /accounts endpoint with the origin_owner_id query parameter to filter accounts for a specific customer:

cURL
Python
TypeScript SDK

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

import requests
import base64
import os

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_123"},
    headers=headers
)

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

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", ... }
// ]

Each returned account carries its origin_owner_id, origin_owner_name, provider, and status. See the List Accounts API reference for the full response schema.

Available filters

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:"

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`. See account status

Build an owner dashboard

Here’s how to build a dashboard showing each customer’s connected accounts:

Python
TypeScript SDK

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)

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

Monitor account health

Track the health of your customers’ connected accounts, using getOwnerIntegrations from the previous section:

Python
TypeScript SDK

def get_account_health_summary(owner_id: str) -> dict:
    accounts = get_owner_integrations(owner_id)

    return {
        "total": len(accounts),
        "active": sum(1 for a in accounts if a.get("status") == "active"),
        "needs_attention": sum(
            1 for a in accounts if a.get("status") in ("error", "inactive")
        ),
        "by_provider": {
            a.get("provider", "unknown"): a.get("status", "unknown")
            for a in accounts
        },
    }

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

Instead of polling, subscribe to the account lifecycle events — account.created, account.updated, and account.deleted — to keep your system in sync as customers connect and disconnect tools. See Platform Events for the payloads and Webhooks for setup.

Connect Session

Set the origin owner fields when your customers link their accounts.

Handle Account Events

React in your backend as customers connect, re-authenticate, or disconnect.

Organizations & Projects

Isolate customers at the project level — regions, environments, API keys.

List Accounts API

Full API reference for listing accounts.

​How customers stay isolated

​Identifying the client on each account

​Provisioning at scale

​List accounts by owner

​Available filters

​Build an owner dashboard

​Monitor account health

​Webhooks for account changes

​Related

Connect Session

Handle Account Events

Organizations & Projects

List Accounts API

How customers stay isolated

Identifying the client on each account

Provisioning at scale

List accounts by owner

Available filters

Build an owner dashboard

Monitor account health

Webhooks for account changes

Related