Account switcher & multi-account analytics — frontend integration

This guide describes the creator (Sanctum) API for multi-account login, backend-owned master/child account groups, and aggregated dashboard metrics. Client storage, UI, and routing are owned by the frontend team.

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 — the first account that links others; sees all linked children after login (account_group.role === "master").
2. Child account — linked under a master; login returns only self plus account_group.master metadata — no sibling list, no group management.
3. Relationships are stored in account_group_members on the backend (survive logout, browser reset, device changes).
4. Switching — master may call POST /api/user/linked-accounts/{childUserId}/session to obtain a child token, or use their own token for master-scoped aggregate APIs.
5. Combined KPIs — POST /api/dashboard/summary/aggregate merges metrics for masters 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 children via API.
master	Non-empty list of children (metadata only, no tokens)	null	Show account switcher for all linked children; use session endpoint or aggregate.
child	[] (always)	Master summary object	Show one account only; hide sibling/master group UI.

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 child: { "email", "password" }. Master/standalone only.
DELETE	/api/user/linked-accounts/{childUserId}	Bearer	Unlink one child. Master only.
POST	/api/user/linked-accounts/{childUserId}/session	Bearer	Master obtains child user + token for switching.
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: all linked children. Child/standalone: 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 child credentials (or use batch login only for initial bootstrap — prefer persisted link API).
3. Switch to child: POST /api/user/linked-accounts/{childUserId}/session → store returned token keyed by child_user_id.
4. Combined dashboard: POST /api/dashboard/summary/aggregate with master bearer only (no additional_tokens required).
5. Remove child: DELETE /api/user/linked-accounts/{childUserId}.

Child

1. Login → role === "child", empty linked_accounts.
2. Do not show other linked accounts or accept additional_tokens on aggregate.
3. Logout should revoke only the current session (POST /api/logout) — do not clear other users’ tokens from storage unless the user explicitly removes all accounts.

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/child links are server-side; possession of a stranger’s token does not add them to aggregate.
• additional_tokens on aggregate is ignored for masters and standalone; forbidden for children.
• Affiliate master_slave is a different feature — do not conflate with account switcher groups.

---

Related docs

• Auth — linked-account routes and account_group fields.
• Wallet — aggregate semantics.
• Authentication.