> ## 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.

# Multi-Tenant Account Management

> List and manage end-user accounts by owner for multi-tenant applications

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.

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

When you onboard end-users through [Connect Sessions](/guides/embedding-stackone-hub), 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.

<Tabs>
  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    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", ... }
    // ]
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.stackone.com/accounts?origin_owner_id=owner_123" \
      -u "$STACKONE_API_KEY:"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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"]
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

<Tabs>
  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    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;
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>
</Tabs>

***

## Monitor Account Health

Track the health of your owners' integrations:

```typescript theme={null}
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     |

<Card title="Webhooks Guide" icon="bell" href="/guides/webhooks">
  Configure webhooks to receive real-time account updates
</Card>

***

## Related

<CardGroup cols={2}>
  <Card title="List Accounts API" icon="code" href="/platform/api-reference/accounts/list-accounts">
    Full API reference for listing accounts
  </Card>

  <Card title="Connect Sessions" icon="link" href="/platform/api-reference/connect-sessions/create-connect-session">
    Onboard end-users with origin\_owner\_id
  </Card>

  <Card title="Accounts Dashboard" icon="users" href="/guides/accounts-section">
    Manage accounts in the StackOne dashboard
  </Card>

  <Card title="Actions Metadata" icon="bolt" href="/api/actions-metadata">
    Build custom UIs with available actions
  </Card>
</CardGroup>