Personas

The platform has five personas but four frontend apps — the Sales-Manager is a role inside the broker app, not its own app. Every end-user persona authenticates with a Laravel Sanctum ability-scoped token; Passport is only for service-to-service calls (the CRM webhooks). The docs that say “Passport password grant for the shopper” are stale — verified against the login code.

Persona	App	How they log in	Token ability	Mainly does
Shopper	orascom-shopper-app	Phone + OTP (passwordless)	access-shopper-api	Browse & buy units, reserve, pay, EOI, download the sales-offer PDF
Broker	orascom-broker-app	Email + password (email-OTP at registration; Oman gets a scoped pre-reg token, ability access-pre-registration-broker-api)	access-broker-api	Submit leads, EOIs, commissions; Oman pre-registration
Sales-Man	orascom-sales-man-app	Microsoft / Azure AD SSO (token via ?token=)	access-sales-man-api	Leads → pipeline → meeting → customer → close a sale; every request carries a country header
Sales-Manager	orascom-broker-app (role-gated)	Email + password	access-sales-manager-api	Analytics only — revenue, commissions, rankings
Shopper-Admin	orascom-shopper-analytics-app	Email + password	access-shopper-analytics-api	Analytics only — funnels, demographics, behaviour

Plus a machine persona — the CRM middleware — which calls back into the portal over webhooks using Passport client_credentials. The token is minted with the middleware-webhook scope, though the webhook routes apply the bare client guard with no per-route scope check. (Don’t confuse this with portals-api — that’s the scope on the reverse leg, backend→middleware.)

What each one is

• Shopper — the public customer. Passwordless login (phone → OTP). Drives the whole purchase state machine (browse → reserve → pay → finish). Sees units from the local published mirror, not live CRM.
• Broker — external sales agents. Egypt/global brokers self-register against an email whitelist; Oman brokers go through a bespoke multi-step pre-registration reviewed by an ODH admin in Voyager. Submit leads and EOIs, see commissions.
• Sales-Man — internal ODH agents, authenticated by Microsoft SSO. The only persona that creates a formal sale end-to-end; their writes land in Dynamics 365 via the Link-Dev tier. Every request must carry a validated country header.
• Sales-Manager — a reporting role inside the broker app (not a separate app): revenue, commissions, and agent rankings. No transactional endpoints.
• Shopper-Admin — the analytics persona over shopper behaviour (funnels, demographics). Read-only.

Auth in one line

Every end-user persona = a Sanctum ability token (access-<persona>-api). Shopper logs in by phone+OTP, Sales-Man by Microsoft SSO, the rest by email+password. Passport is reserved for service-to-service client_credentials (the CRM-middleware webhooks). Tokens live in the browser’s localStorage, one key per app — the key names are env-configured (NX_*_ACCESS_TOKEN_KEY); the shipped defaults (broker_access_token, salesman_access_token, …) are what you’ll see.

ArchitectureHow the apps, backend, middleware and CRMs fit together.

Broker submits a leadOne persona's journey through the whole stack.