The Laravel example hosts the Composer package and exposes /api/chat. React, Vue, the HTML widget and custom JavaScript clients can share this API and Reverb server. No hosted chat provider is required. The central application provides its own account login and administrator-managed services/providers/accounts. The reusable Composer package still accepts a host identity adapter.
Identity boundary#
Every request must be authenticated by the host middleware. HostAdapter resolves the trusted identity: id, name, role (customer, seller, admin), service_id, and optional provider_id. Its providers method supplies the authorized provider directory for that service. Browser service/role options do not create permissions. Different providers in one service use different provider IDs; members of a provider team map to the same provider ID and retain their own identity ID.
The standard website sends {email,password,remember} to POST /api/auth/login and has no role selector. Use distinct emails for each platform administrator, service administrator and team/customer account. The server resolves the account's stored role and scope and returns a user-scoped token, expiry and authenticated account metadata. POST /api/auth/logout revokes the current token. GET /api/auth/me returns account permissions. The website restores tokens from tab storage; Remember me uses persistent browser storage with a bounded server expiry. See the session policy. Service/account disablement is enforced by the server.
A platform_admin manages all services and accounts, but must select a service through POST /api/auth/scope to use chat. This replaces the token and chat identity maps to admin for the authorized selected service. A service admin manages only that service's providers and customer/seller accounts. Account flags in the login result control menu availability; backend checks independently authorize actions.
Local /api/demo/login remains development-only, with seeded fixtures. Do not deploy with APP_ENV=local to expose those accounts. The standalone application requires an operator-created first platform admin; public signup is absent. Bootstrap command, precise endpoint schemas, password requirements and role rules are in authentication and management. Do not copy a seeded local database into production: demo-marked accounts are blocked there, and production provisioning must use fresh migrations and the secure bootstrap command.
Connecting a host#
- Use the central application's account login, or configure your host's authenticated middleware when embedding the package.
- Implement
ServiceChat\Contracts\HostAdapter, deriving service and role from trusted server-side account/membership records. Configureservice-chat.adapter. - Protect the broadcasting authentication endpoint with the same identity resolution. Keep REST and channel authorization consistent.
- Give the browser a user-scoped token through the host's authenticated session flow. Pass it or a token callback to
ChatClient; never send service-wide privileged credentials to the browser. - Configure allowed API origins and Reverb origins, the public API URL and the public Reverb connection key. Keep the Reverb secret server-side.
- Test customer/provider/admin allowed access and cross-service/provider denial.
The standalone server now provides service-key management and a customer/seller server identity exchange. Your host still authenticates users and authorizes role/provider membership. Onboarding is administrator-managed; there is no public signup, refresh-token endpoint or webhook integration. Administrator identities use website login. See other backends.
API and realtime locations#
The SDK API root is configurable. Set authEndpoint for a custom private-channel authorization location; the default convention is /api/broadcasting/auth on the same API server. The Next workspace exposes NEXT_PUBLIC_CHAT_AUTH_ENDPOINT. Custom routes still need the same host identity middleware and denial checks.
Bearer requests use CORS without cookies. The current SDK does not implement cookie-session/CSRF cross-origin transport. CORS allowlists are transport policy; they never replace identity and conversation permissions.
The database stores durable messages. Reverb events accelerate updates; they are not a message archive. The SDK reconciles saved messages after subscription and reconnection, merging IDs. The inbox needs explicit refresh to discover new conversations. Feature/verification boundaries are listed in compatibility.
The standalone host uses a token-bound socket grant registry and guarded Reverb channel manager to enforce expiry/revocation even after subscription. It rechecks authorization before every outgoing payload and periodically disconnects idle revoked sessions. Keep API and Reverb on the same authoritative database and restart both processes after auth/guard upgrades. The generic package and other hosts do not automatically inherit this policy. Multi-node deployment of the guard remains unverified; see security.
The optional API-only compatibility field account_role remains available to integrations managing existing accounts that share an email. Send the stored role as account_role in that integration; the standard website does not expose a shared-email account selector. Omitting it is backward compatible only for an email identifying exactly one account. The discriminator never changes service/provider permissions. See the canonical auth contract. This affects standalone account login only; framework SDKs still consume user-scoped tokens.