Invitations

Invite — POST /invitations

• Optional sendEmail (boolean, default true): QBitFlow emails the person a link of their own, in QBitFlow's name, stating a member's terms: who pays the fees (the organization's commission on the listed price when its checkout.customerPaysProcessingFee is on in the invitation's mode, buyers paying QBitFlow's fee on top; on what remains after QBitFlow's fee when it is off; without a commission, whether QBitFlow's fee comes out of their sales; network fees always the buyer's), then where their share goes (the percent they keep; held until the organization trusts them, or directly to their wallet). That link has its own token, never returned: only the email carries it, so signing up through it proves the inbox and needs no confirmation email. false sends no invitation email: show or send the returned link yourself (your own onboarding, your own email). The returned link works either way; a person signing up through it gets the sign-up confirmation email first (§ The invited person: you hold that link too, so an account is only created for a confirmed address). One with an account, or signing in with a provider, gets none. A non-boolean → 400 validation_failed on sendEmail.
• A member (role: user) is invited in the request's mode. holdFunds is required: true holds their payments until the organization trusts them (POST /members/:userUuid/trust), false pays them directly. Optional organizationFeePercent (a string, "0" to "50", default "0").
• A team invitation (role: admin) is mode-free, from the dashboard only (an API key → 403), without holdFunds or organizationFeePercent (→ 400 validation_failed on role). Its test, holdFunds and organizationFeePercent are absent (a member's invitation always has all three).
• Optional redirectUrl (http_url): where the person goes once they accepted, with ?invitationUuid=<uuid> (it was ?invitationId=).
• The invitation expires after 7 days. A new invitation of the same person and mode replaces the open one (its link stops working). Someone already there with that role and mode → 409 already_joined (a live member can still be invited in test).
• holdFunds: true with organizationFeePercent > 0 (a marketplace's default): the member's payments go to the organization's wallet, the fee is withheld from what the organization owes them, and a release pays the net (Members and held funds § The organization fee on held funds). Held members sell subscriptions too. The organization fee is only taken on the chains where the organization has a wallet (and held funds need that wallet anyway).
• A member → 403; validation → 400 validation_failed (email, role, holdFunds).
• At most 50 invitations an hour per organization, both modes and every credential together (LimitPerOrganization(invitations)) → 429 rate_limit_exceeded past it, whether or not it emails the person. A caller refused for its role spends nothing.
• Idempotency-Key (idempotency): a retried invitation with the same key answers the first one (CreatedInvitation, the same link) and sends no second email.

List and revoke

• GET /invitations → 200 a page (newest first by createdAt; limit default 20, at most 100; cursor = the previous page's nextCursor) of the organization's invitations of the request's mode, and from the dashboard of its team too: an API key lists member invitations only (role: user), the team being managed from the dashboard. An accepted invitation names who accepted it with acceptedByUserUuid (their Member.userUuid) and acceptedAt; a revoked one has revokedAt (both absent otherwise). ?status=pending|accepted|revoked|expired filters. Another organization's never appear.
• DELETE /invitations/:uuid (re-authentication) → 204 with no body: its link stops working (GET /invitations shows it revoked). Already accepted or revoked → 409 conflict; a team invitation with an API key → 403; another organization's or another mode's → 404.

The invited person

• GET /invitations/preview/:token (public) → 200: organizationName, the invited email, role, test (absent for the team), status, expiresAt, and a member's terms, shown before they accept: holdFunds, organizationFeePercent and customerPaysProcessingFee (absent for the team). customerPaysProcessingFee is the organization's checkout.customerPaysProcessingFee in the invitation's mode when the link is opened (not when it was sent): true, buyers pay QBitFlow's fee on top of the price, so the commission is on the full listed price (a $100 sale at 20 %: $20 to the organization, $80 to the member); false, QBitFlow's fee comes out of the sale and the commission is on what remains. Members can't set that setting; a checkout's own fees.processingFee still decides for itself. Either link's token works (the returned one and the emailed one). A token that isn't one (not letters and digits, or longer than 128) → 400 validation_failed on token; a wrong token → 400 invalid_invitation.
• POST /invitations/accept { "token" } with a session (dashboard-only): the signed-in account must be the invited address's (403 invitation_email_mismatch otherwise). → 200 the session re-signed where they joined (SpaceSession + redirectUrl): their member space of the invitation's mode, or the organization's live space for the team. A member invited to the team becomes an admin. An account that already belongs to other organizations joins this one too (§ Several organizations per account).
• An account removed from its organization (no membership left) signs in without an organization (Account and credential § Sessions) and accepts with POST /invitations/accept (its session reaches it), or signs in with the invitation's token: POST /auth/login { email, password, invitationToken } → the Login where they joined, with redirectUrl. The invited address must be the account's (403 invitation_email_mismatch). Their former personal space reopens with this invitation's terms, their data still there.
• There is no list of the invitations an account received: the link (its token) is how one is previewed and accepted.
• A member joining (accept or sign-up confirmation) publishes member.joined to the organization's endpoints, in the mode they joined (Webhook events): the marketplace learns who joined, with their userUuid, without polling. A team join publishes none.
• POST /invitations/sign-up { token } (public) → 200 SignUpRequested (message, and confirmationToken on the emailed link's path):
  • Through the emailed link (its token only ever reached the invited inbox): a free address gets confirmationToken at once, no second email. Post it to …/sign-up/confirm with the account's name and password.
  • Through the returned link (the organization holds it too, so it doesn't prove owning the address): a free address gets a confirmation link by email (/invitations/sign-up/confirm?token=, valid 24 hours, subject "Confirm your email to join <organization> on QBitFlow"), and no confirmationToken.
  • An address with an account, through either link: an email saying so (sign in and accept), and no confirmationToken, the same answer as an emailed confirmation.

The account is only created on confirmation. Capped like every confirmation email (errors): 5 an hour per invitation, 20 an hour per client IP → 429 rate_limit_exceeded.

• POST /invitations/sign-up/confirm { token, firstName, lastName, password } (the token: the confirmationToken, or the confirmation email's; whoever proved the address chooses their name and password) → 201 the Login of the new account where they joined, with redirectUrl. A wrong, expired or used confirmation → 400 invalid_confirmation_token.
• An invitation expired, revoked or already accepted → 400 invalid_invitation.
• An invitation of a closed organization → 400 invalid_invitation: closing an organization revokes its pending invitations, and an acceptance (accept or sign-up confirmation) never brings anyone or any space back into a closed organization, even for an invitation left pending.

Several organizations per account

• An account may belong to several organizations, with a role in each, and own several. Accepting an invitation (/accept, or a login with invitationToken) with an account that is already an active member, admin or owner of another organization succeeds like any acceptance: it keeps its other memberships, and its session moves to where it joined. A seller who already uses QBitFlow joins your platform with the same account.
• Its spaces in every organization are listed by GET /account/spaces (and Login.spaces), and its session switches between them (POST /auth/switch-space, Account and credential § Sessions). Each session acts in one space: one organization's data never shows in another's.
• An account removed from its organization belongs to none: it accepts normally (§ The invited person).

Test-mode members

• A test member is a real account too: invited by a test key (or the dashboard in test mode), they accept from a real inbox (the confirmation email) and their test space is theirs. There is no way yet to create accepted test members from a key (for CI); use real addresses you control (you+seller1@yourdomain.com), invited once and kept.