# Account structure

Salaxy arranges accounts in a tree. Your technical account is the root, and every customer company hangs below it, either directly or through an accounting firm. The shape you pick decides who sees which companies, whose settings apply and how you create accounts, so choose it before you build.
Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production.

*Diagram: Three structures side by side. Two-tier: your technical account has customer companies directly below it. Three-tier: your technical account has accounting firms below it, and each accounting firm has its own customer companies. Mixed: your technical account has both accounting firms and directly attached customer companies, and the accounting firms have customer companies of their own. A customer company always has exactly one parent. (Grey: your side. Purple: the customer company, which has exactly one parent in every structure.)*

## The rules

- A **customer company has exactly one parent**: your technical account directly, or an accounting firm. Never both.
- The **payment channel** belongs to the technical account and reaches every account below it through [service models](https://code.salaxy.com/integration/service-models.md). No tier below can swap in its own payment channel.
- **Accounting models** (the charts of accounts) are also distributed through service models, not attached to accounts one by one.
- **Employees and other end users are not in the tree.** They only receive salary slips and may sign in to see their own pay.
- **The tree is not the access list.** Being a parent gives no access by itself. Access comes from an authorisation on the company's account that names your account, and it is all-or-nothing: whoever can reach the company can do everything the company account can do.

The terms behind the tree (account, worker, employment, payroll) are in [Core concepts](https://code.salaxy.com/about/concepts.md).

## Which fits you?

### Two-tier: partner to customer company

Choose this when you onboard customer companies directly and you are, or act as, their accounting firm. Every customer company is created directly under your technical account.

**Two-tier: how it works:**
- You create each customer company with `POST /v03/api/partner/company` and **leave `proxyPartner` out**. See [Partner-initiated account creation](https://code.salaxy.com/security/account-creation.md).
- Customer companies that are accounting firms themselves are onboarded as ordinary customer companies.

### Three-tier: partner to accounting firm to customer company

Choose this when your customers are accounting firms that serve their own customer companies. The accounting firm tier gives each firm its own view of only its customer book in Salaxy Pro.

**Three-tier: how it works:**
- Create the **accounting firm account first**, without `proxyPartner`. Then create each customer company with `proxyPartner` set to the accounting firm's account id, so the firm becomes the company's parent.
- Your technical account needs access to the accounting firm. It does not need to be authorised to each customer company separately: the token flow can name the accounting firm as a proxy, and Salaxy checks both steps (you to the firm, the firm to the company). See [Impersonation flow for SSO](https://code.salaxy.com/security/impersonation.md), the `salaxy_proxy_act` claim.
- **The proxy step reaches everything the firm can reach.** You cannot limit it to a subset of the firm's companies.
- The parent is set only when the company has none. A company that already has a parent keeps it, so moving it needs the explicit re-pointing call below.
- The accounting firm's users work in Salaxy Pro or through the [Pro API](https://code.salaxy.com/integration/pro-api.md). How the firm's account is created: [Accounting firm account creation](https://code.salaxy.com/integration/accounting-firm-accounts.md).

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/v03/api/partner/company` | Create or find a customer company or accounting firm. `proxyPartner` names the parent |
| `POST` | `/v01/api/pro/accounts/{accountId}/partner` | Make the current account the company's primary partner. Optional `serviceModelId` query parameter |
| `DELETE` | `/v01/api/pro/accounts/{accountId}/partner` | Remove the current account as the company's primary partner |

The re-pointing calls exist only in the Pro API, which has no v03 version. The same endpoints are under `/v04/api/pro/` in the [v04 reference (beta)](https://code.salaxy.com/reference/rest/v04/pro.md). See [Pro API](https://code.salaxy.com/integration/pro-api.md).

### Mixed: some directly, some through accounting firms

Choose this when only part of your customers have an accounting firm in between. Create each customer company by the two-tier or three-tier method, depending on who its parent is. The rules above apply to each branch separately.

**Mixed: how it works:**
- Decide per customer company at creation time: with `proxyPartner` if it belongs to an accounting firm, without it if it belongs directly to you.
- Every company still has exactly one parent, so the question "who is this company's parent?" always has one answer.
- Service models can differ per branch. See [Service models](https://code.salaxy.com/integration/service-models.md).

## How to choose

| If … | Then |
|---|---|
| You are the accounting firm for all your customers | Two-tier |
| Your customers are accounting firms with their own customer companies | Three-tier |
| Some customers come through accounting firms and some do not | Mixed |
| You are not sure | Ask at the kick-off. A company that already has a parent keeps it, so changing the structure later needs the re-pointing call |

Who has a contract with whom in each structure: [Contract options](https://code.salaxy.com/integration/contract-options.md).

## Test it

1. Create two customer companies with `POST https://test-secure.salaxy.com/v03/api/partner/company`, as in [Partner-initiated account creation](https://code.salaxy.com/security/account-creation.md). For a three-tier test, create an accounting firm first and use its id as `proxyPartner`.
2. Get a token for each company ([Impersonation flow for SSO](https://code.salaxy.com/security/impersonation.md)) and call `GET /v03/api/session/current`. `currentAccount` shows the company you act as.
3. For a three-tier test, get a token for the accounting firm and call `GET /v01/api/pro/accounts`. The companies created with the firm as `proxyPartner` are in the list.

## Checklist

- You have chosen two-tier, three-tier or mixed, and the choice is written down for both sides.
- Every customer company is created with the right `proxyPartner`, or none.
- You handle the case where a company already exists under another parent: the creation call does not move it.
- Your tokens name an accounting firm as a proxy only when your account is authorised to that firm.
- Your product shows a user only the companies that user is entitled to. Salaxy Pro does this for accounting firms; in your own UI, you do it.

**Next:** [Contract options](https://code.salaxy.com/integration/contract-options.md)
