Account switcher & multi-account analytics — frontend integration

This guide describes the creator (Sanctum) API for multi-account login, backend-owned master/sub-account groups (directional linking), and aggregated dashboard metrics.

Implementation note: The production webapp already implements the core switcher (link, switch via session token, master aggregate). This doc remains the API contract for web and mobile clients.

Environments

Environment	API base	Swagger UI
Development	https://fangate.co/api	https://fangate.co/api/documentation
Production	https://fangate.info/api	https://fangate.info/api/documentation

Static developer docs: https://docs.fangate.app

---

Goals

1. Master account — links sub-accounts; sees only sub-accounts it linked (linked_accounts after login when role is master or hybrid).
2. Sub-account — linked under one or more masters; login returns only self plus optional account_group.master metadata — no siblings from another master’s group.
3. Hybrid — both linked under a master and has its own linked sub-accounts; may link/unlink and aggregate its own set only.
4. Relationships are stored in account_group_members on the backend (directional; same sub-account may appear under multiple masters).
5. Switching — call POST /api/user/linked-accounts/{childUserId}/session only for sub-accounts you linked.
6. Combined KPIs — POST /api/dashboard/summary/aggregate merges metrics using persisted links only (not client-supplied tokens).

---

Account group (account_group)

Returned on POST /api/login, POST /api/register, GET /api/user, and each POST /api/login/batch session row.

{
  "role": "master",
  "master": null,
  "linked_accounts": [
    {
      "id": 12,
      "child_user_id": 42,
      "email": "child@example.com",
      "display_name": "Child Creator",
      "currency_id": 1,
      "currency_code": "EUR",
      "linked_at": "2026-05-18T12:00:00+00:00"
    }
  ]
}

role	linked_accounts	master	Client behaviour
standalone	[]	null	Single-account UX; may link sub-accounts via API.
master	Non-empty list (metadata only, no tokens)	null	Show switcher for linked sub-accounts; session endpoint or aggregate.
sub_account	[]	One master summary (if linked)	Show one account only; no sibling list from other masters.
hybrid	Own linked sub-accounts only	null	Switcher for your links; you may link more; aggregate own set only.

Do not treat locally stored tokens as proof of access to other creators — use account_group from the latest login / GET /api/user.

---

Endpoints

Method	Path	Auth	Description
POST	/api/login	No	Returns user, token, account_group.
POST	/api/register	No	Same account_group shape (usually standalone).
GET	/api/user	Bearer	Returns user + account_group.
POST	/api/login/batch	No	Up to 10 accounts; each session includes account_group.
GET	/api/user/linked-accounts	Bearer	Refresh account_group for the current user.
POST	/api/user/linked-accounts	Bearer	Link sub-account: { "email", "password" }.
DELETE	/api/user/linked-accounts/{childUserId}	Bearer	Unlink one sub-account you linked.
POST	/api/user/linked-accounts/{childUserId}/session	Bearer	Obtain sub-account user + token when you linked them.
GET	/api/user/sessions	Bearer	App sessions (api tokens) for current user only.
DELETE	/api/user/sessions/{tokenId}	Bearer	Revoke one app session.
GET	/api/dashboard/summary	Bearer	Single-account KPIs.
POST	/api/dashboard/summary/aggregate	Bearer	master / hybrid: own linked sub-accounts. Others: self only.

See Auth and Wallet.

---

Recommended client flow

Master

1. Login → read account_group.linked_accounts.
2. Add account: POST /api/user/linked-accounts with sub-account credentials (prefer persisted link API over batch login alone).
3. Switch to sub-account: POST /api/user/linked-accounts/{childUserId}/session → store returned token keyed by child_user_id.
4. Combined dashboard: POST /api/dashboard/summary/aggregate with bearer only (no additional_tokens required when you have links).
5. Remove sub-account: DELETE /api/user/linked-accounts/{childUserId}.

Sub-account (sub_account)

1. Login → role === "sub_account", empty linked_accounts, optional master metadata.
2. Do not show other masters’ linked lists or send additional_tokens on aggregate unless you later become hybrid.
3. Logout should revoke only the current session (POST /api/logout).

Hybrid

Same as master for your linked_accounts; same privacy rules as sub-account for accounts linked to you by others (you do not inherit their switcher list).

Logout (important)

POST /api/logout revokes one token. Do not call clearAllSessions() on every logout — remove only the active account from local storage unless the user chooses “log out of all accounts”.

---

Aggregate response — UI rules

Unchanged from prior delivery:

• currency_unified: true only if every merged account shares currency_id.
• Root wallet_balance: only when currency_unified is true.
• Per-account buckets: accounts[].wallet_balance.

---

Security

• Master/sub-account links are server-side and directional; possession of a stranger’s token does not add them to aggregate.
• additional_tokens on aggregate is ignored when the bearer has linked sub-accounts; forbidden for pure sub_account without own links.
• Affiliate master_slave is a different feature — do not conflate with account switcher groups.

---

Related docs

• Account switcher — frontend implementation — detailed checklist, TypeScript types, flows, and webapp migration steps for the client team.
• Auth — linked-account routes and account_group fields.
• Wallet — aggregate semantics.
• Authentication.