Identity & organizations

Money & accounts covers what moves. This page covers who: the identities that can hold money, the organizations layered on top of them, and how the SDK keeps "who is acting" explicit.

The Capxul user is the atom

A Capxul user is a person with their own personal Account, identified by a Capxul user ID. It is the atomic money-holding identity: everyone on the platform is a Capxul user first, and every other structure is layered on top. There is no org-only identity — an organization's founder, members, and payees are all Capxul users (or people invited to become one).

Organizations are layered on top

An Organization is a shared entity with its own treasury Account and a globally-unique, claimable Organization ID — today, the org handle. The treasury is an ordinary Account in the domain sense (opaque id, balance, available balance); what makes it organizational is who may spend from it and under what authority.

Org money movement is authorized under roles: an org payment is made by a member acting within their role and its spending limits, not by whoever happens to hold a credential. The SDK exposes members, roles, treasury, and payroll as the org surface; the machinery that enforces authority stays underneath.

Member means authority, not payment history

A Member is a Capxul user who holds a role in an organization. Membership is about authority inside the org — nothing else. In particular:

Being paid by an organization does not make you a member.

The domain keeps two invitations strictly apart. Inviting someone into the org with a role makes them a member. Paying someone merely invites them to become an individual Capxul user so they can claim the money. A payroll roster can be full of people with no standing in the org at all — which is exactly right: your salary recipients should not accidentally acquire treasury authority.

Handles are claimable IDs

A claimable ID is a public, globally-unique identifier that a recipient can be paid at and later claim. Organizations have one (the org handle), and a personal Capxul user has one too: the Handle chosen at onboarding — the username, with uniqueness and reservation rules. Handles are what make "pay @fatima" possible without either side ever seeing an address.

The acting entity is explicit

Most surfaces exist twice: your personal Account has an inbox, an address book, payment requests — and so does each organization. The acting entity is which of those you are operating as.

The SDK deliberately has no hidden global "active org". Scope is stated at the call site:

client.account.requests.list();      // acting personally
client.org(orgId).requests.list();   // acting as the org

React follows the same model with explicit actor scopes passed to hooks:

const personalInbox = useCapxulInbox(capxulAccountScope);
const orgInbox = useCapxulInbox(capxulOrgScope(orgId));

If your product has an entity-switcher menu, the selected entity is your app state — you hold the chosen orgId and pass the matching scope to the hooks on each screen. (useCapxulSwitchActingEntity exists as a stable mutation seam for switcher UIs, but it carries no SDK side effect; the switch itself is the consumer's local state.)

The trade-off is honest: explicit scoping means passing a parameter where a global would have been terser. What it buys is that no part of the app can silently change which entity another part is operating as — a property worth a great deal when the operations are payments.

Recipients are typed references

When you name a counterparty, you use a typed Ref, never a raw address:

{ kind: "email", email: "recipient@example.com" }
{ kind: "handle", handle: "fatima" }
{ kind: "orgHandle", orgHandle: "acme" }
{ kind: "payeeId", payeeId: "payee_123" }

Each kind maps onto the identity model: a Capxul user (by handle or email), an organization (by org handle), an email that is not yet a Capxul user (which produces a claimable payment), or a saved Payee — an external payout counterparty whose settlement details live inside the Payee record, referenced by an opaque id. The app names who; Capxul resolves where that intent settles.

The bigger picture

The identity model mirrors the money model: opaque ids instead of addresses, typed references instead of raw destinations, and authority made explicit instead of ambient. One consequence is worth internalizing early — questions like "is this person in the org?" and "has this person been paid by the org?" have different answers on purpose. When you can explain why a payroll recipient is not a member, you have this page.

Whether a given identity is ready to hold and move money is a separate, time-ordered question — that is the account lane.