Sign in and invites

Goal

Access the correct tenant workspace with an active membership, or create your first company.

Who it is for

Everyone invited to a BlueMatrix tenant. Creating a brand-new company uses self-serve register. Inviting teammates needs member.manage. Switching to another workspace needs an existing membership on that tenant.

Preconditions

• You know the staff app URL for your organization.
• For invitees: your admin already added you under Members, or you registered yourself.
• Membership must be active; a suspended tenant blocks business data routes (you may still reach auth / /me / subscription lifecycle screens).

Steps — sign in

1. Open the staff app. Unauthenticated visits redirect to Accounts (accounts-dev.bluemtx.com / accounts.bluemtx.com). Vite staff ports (dev.bluemtx.com:5173, POS :5174, Ops :5177, merchant :5175) are passed as an allowlisted origin so login hands back to that port instead of the built host.
2. Sign in with Email and Password, a passkey (fingerprint / Face ID / Windows Hello / synced Google or Apple passkey), Email me a sign-in link (magic link), or Continue with Google / Microsoft / Apple when those OAuth apps are configured. Forgot password lives on the same host. New Google/Apple users without a workspace continue into the signup wizard.
3. If your workspace MFA policy requires it and you already enrolled an authenticator app, password / social / magic-link sign-in asks for a TOTP or recovery code before handoff. Passkeys satisfy MFA. Enrol or manage TOTP under ERP Sessions & devices. Soft enforce: if MFA is required but you have not enrolled yet, you still receive a session and should set up the authenticator.
4. After a successful sign-in, Accounts hands a one-time code to ERP, POS, Ops, or Merchant (/auth/enter?code=…&next=…). The Sanctum token is stored on that app origin — never in the redirect URL. ERP, POS, and Ops redeem the code in the router and open the requested page directly. A thin progress bar is the only waiting UI; there is no intermediate “Entering workspace” screen. Merchant still completes its own enter step. If the code is missing, expired, reused, or rejected, or the session cannot start, ERP, POS, and Ops clear the incomplete sign-in, remove the code from the address bar, and show Return to sign in. That action keeps a safe in-app destination and does not retry the code.
5. On success you land on the dashboard (or POS / Ops home) for the membership the server scopes to your Sanctum token (tenant:{uuid} — last tenant you used if you are still a member, otherwise your first membership). Tenant is never taken from the request body.

Steps — create your first workspace

1. From login, choose Create account (/signup).
2. Sign in with Google or Microsoft (if configured) or fill Your name, Email, Password.
3. Pick a trial plan (no card), then company, country pack (with a live preview), optional industry, and sample vs clean books.
4. Create workspace provisions the tenant and Owner membership via TenantProvisioner (POST /api/signup/complete), then signs you into that workspace.

Steps — accept an invite

1. An admin opens Members (member.view to list; member.manage to invite) and chooses Add member (name, email, role).
2. You receive email You have been added to {tenant}. New users get a Set your password button to Accounts (/reset-password?email=…&token=…); existing users get Sign in to BlueMatrix.
3. Sign in (or set password via the reset flow your invite describes), then open that workspace from the switcher if you belong to more than one.

Steps — switch workspace

1. In the top bar, open the workspace switcher (Switch workspace).
2. Pick another membership ({name} · {role}).
3. The client calls POST /auth/switch-tenant with that tenant_id, receives a new token, refreshes /me, and resets workspace tabs.
4. If you have tenant.manage, the menu also offers New workspace (opens onboarding).

Result

You see only the navigation and modules your role and enabled_modules allow. Help, locale, and My Work appear in the top bar.

Hard stops

• Wrong email/password → 422; UI shows Invalid email or password.
• Invite of an email that is already a member → rejected.
• Inviting a user who already has a BlueMatrix account when allow_invite_existing_users is off → 422 (Inviting users who already have a BlueMatrix account is disabled…). Controlled under Members setup.
• Switch to a tenant you do not belong to → 422 (You do not have access to this tenant.).
• Suspended tenant → business routes 403 (This tenant is suspended.).
• Ops “open workspace” uses /auth/enter?code= (one-time handoff; the token is not in the URL). ERP opens the destination directly. A bad or reused code shows Return to sign in instead of retrying.

Related

• Navigate BlueMatrix
• New workspace (onboarding)
• Users and roles
• Tenant settings