invite-with-password

Invite With Password

When to use this

The app owns its account UI: a custom login form, a custom onboarding screen, its own password setup and reset — the user never leaves the app and never sees a Fusebase auth page. Typical asks: "invite my clients into the portal app", "our own branded sign-in", "let them pick a password when they accept the invite".

Without this, an invited user has no password they know, so the only way in is the platform's "Trying to reset your password?" email — nonsense for somebody who never registered, and it drops them onto a platform page in the middle of your onboarding. setFusebaseInitialPassword is what makes an app-owned form possible: the invitee sets their first password inside the app.

The reset half of app-owned auth is a different op: requestFusebaseRestoreKey mints a restore key without sending the platform email, so the app can send its own branded reset mail — see fusebase-gate/references/fusebase-auth.md § Password Restore. This skill covers the first password only.

Flow

Invite → invitee opens the app through the magic link → app shows a Create your password form → the account signs in with email + password from then on. No platform email beyond the invite itself.

Both pre-provisioning paths — addOrgUser (orgRole: 'client', autoConfirmClientInvite: true) and createAppMagicLink (addToAccessPrincipals: true) — create an account holding a random password the user never learns, which is why the invitee needs setFusebaseInitialPassword to get one they know.

1. Invite — app backend, process.env.FBS_FEATURE_TOKEN: addOrgUser or createAppMagicLink.
2. Open — invitee clicks the link, the platform activates it, the app host gets the invitee's fbsfeaturetoken. Do the mandatory magic-link exchange first (fusebase-gate/references/fusebase-auth.md).
3. Detect — SPA reads needsInitialPassword from /auth/context. true = this account has never had a password → render the password form. Absent/false → do not offer it.
4. Set — app backend forwards the invitee's own token to Gate. FBS_FEATURE_TOKEN gets 403.
5. Sign in right away — a 200 mints no session and drops every existing session of the account, including the magic-link one, so log the user back in with the password from the same form.
6. Spend the handoff — the login response carries appAuth, not a session id. The backend passes appAuth.authPath to the SPA; the SPA fetches it on its own origin and the browser stores the fbsfeaturetoken that response sets. The app never sets a cookie of its own from a login response.