These endpoints belong to the standalone Laravel host, not the reusable Composer package. All endpoints are under /api. There is no public signup. Ordinary accounts are created by an authorized administrator.
Bootstrap and passwords#
After php artisan migrate --force on a fresh production database, run php artisan chat:bootstrap-admin [email protected] --name="Platform Administrator". The command prompts secretly. For provisioning use --password-stdin and supply exactly one password line over secure stdin, never a command argument or a committed file. It refuses when an active platform admin exists. A cache lock prevents concurrent bootstrap. The password must be at least 12 characters with upper/lowercase letters, number and symbol; validation errors never echo the password. Laravel's configured secure password hasher stores it. There are no default production passwords or users. Never run demo seeding in production; the seeder refuses, and accounts marked is_demo are also denied production login.
Passwords are limited to72 UTF-8 bytes to prevent bcrypt truncation, including at login. Existing local demo passwords are fixture-only. Registration and password changes never accept an arbitrary password hash from clients.
Session endpoints#
| Method/path | Input | Output |
|---|---|---|
POST /auth/login | {email,password,remember?:boolean,account_role?,service_id?} | {data:{token,expires_at,user}} |
GET /auth/me | Bearer token | {data:user} |
POST /auth/logout | Bearer token | 204; revoke current token |
POST /auth/scope | Platform admin Bearer; {service_id} | New login-shaped response, old token revoked |
user is {id:string,name:string,email:string,role:'platform_admin'|'admin'|'seller'|'customer',service_id:string|null,provider_id:string|null,is_active:boolean,active_service_id:string|null,can_manage_services:boolean,can_manage_accounts:boolean}. Management account records use this same shape; active_service_id is null unless presenting a session. Token expiry is UTC ISO8601. Default lifetime is 480 minutes, configured by server-only CHAT_AUTH_TOKEN_LIFETIME_MINUTES. Random 64-character bearer tokens are stored SHA256-hashed; the raw token appears only in login/scope responses. There is no refresh endpoint: sign in again after expiry. Logout revokes only the current token; account updates revoke all that account's tokens. Disconnect old chat clients on logout/scope changes. The standalone Next workspace supports the browser storage policy below; reusable SDKs do not store tokens.
The standard website login sends {email,password,remember}; remember defaults to false. Provision distinct email addresses for platform administrators, service administrators and team or customer accounts. The server resolves the stored role, service/provider scope and management flags after checking that account's password; the login UI does not select or grant a role. A platform administrator signs in unscoped and then chooses an authorized active service for chat. Service administrators and other accounts retain their stored service and cannot request a different one.
Login email is case-normalized. For API compatibility, optional account_role is one of platform_admin, admin, seller, customer; when supplied it must match the stored account role. The same email can identify distinct accounts of different roles, each with its own user ID, password hash, tokens and service scope. Without account_role, login remains compatible only when exactly one account has that email; ambiguous email fails with the same generic401 as invalid credentials. Unknown role values fail validation422. The API field is an account discriminator, never a role grant. Shared-email accounts require an integration that explicitly supplies that field; the standard email/password website does not offer this selection. Attempts share the existing email/IP throttle across roles.
Failure is a generic401; suspended accounts/services and inactive seller providers cannot log in. Normal accounts cannot request another service. A platform admin can log in without scope for global management, or with an active service_id. Unscoped chat endpoints return409 asking for a service. Scoped /api/chat/me presents the platform admin as role:admin within the selected service, preserving actual user ID. Management authorization still uses the real platform role.
Login is limited to five attempts per minute per email/IP and twenty per IP;429 includes Retry-After (CORS exposed). Authenticated API routes use120 requests/minute/IP. Password reset/recovery, MFA, email verification, public signup and session/device listing are not implemented. Operators manage password changes via authorized account update; lost-all-admin recovery requires secure server/operator intervention, not an unauthenticated HTTP route.
Management endpoints#
All use an individual Bearer token and return {data:...} with HTTP200. Global platform admins manage all services; service admins manage only their own service's providers and seller/customer accounts. Customer/seller access is403. Objects outside a service admin's scope are404. GET lists return at most200 records; cursor pagination/search is deferred.
| Method/path | Input/output |
|---|---|
GET /admin/services | Services; platform all, service admin own only |
POST /admin/services | Platform only; {id,name} |
PATCH /admin/services/{id} | Platform only; partial {name,is_active} |
GET /admin/providers | Providers; platform may filter ?service_id=...; service admin fixed own scope |
POST /admin/providers | {id,service_id,name,logo_url?}; service must be authorized |
PATCH /admin/providers/{id} | Partial {name,logo_url,is_active}; service cannot move |
GET /admin/accounts | Accounts; same scope/filter rule as providers |
POST /admin/accounts | {name,email,password,role,service_id?,provider_id?} |
PATCH /admin/accounts/{id} | Partial {name,email,password,role,provider_id,is_active}; service cannot move |
Service {id,name,is_active}; provider {id,service_id,name,logo_url:string|null,is_active}. IDs are globally unique lowercase letters/digits/underscore/hyphen, begin with a letter/digit, at most64 characters. Names max120, public HTTPS logo_url max2048, emails max254. Logo URLs are rendered only as images by supported clients and must not contain credentials or customer-specific paths. Normalized email plus role is globally unique, including inactive/demo accounts; create/update duplicate pairs return422. Email or role changes validate the effective pair, including unchanged fields. Same email/same role across different services is not supported. Created records are active. Accounts require a valid service except platform admins, which have neither service nor provider. Sellers require a provider in that service; customers/service admins have no provider. Platform admins may create platform/service admins, sellers and customers. Service admins can create/update only sellers/customers and cannot edit other service admins or themselves through this endpoint. Roles and scopes come from backend validation, not UI options. Moving an account between services is forbidden; create a separate account.
Account updates revoke every token including the current session when editing oneself. Service disable revokes all scoped service tokens and member sessions; provider disable revokes its seller/team sessions. Re-enable never revives old tokens. The last active platform administrator cannot be disabled/demoted (409). Creating a second administrator for recovery is recommended; simultaneous admin mutation uses SQL row locks and needs production engine/load verification.
Management changes create chat_management_audit rows with actor/action/target and nonsecret details; passwords/tokens are never included. Audit browsing/export and automated retention are deferred. No delete endpoint exists; disabling preserves chat history.
Reverb revocation enforcement#
The own central app registers GuardedChannelManager for Reverb1.12. Only supported private chat channels can be subscribed. Broadcasting auth creates a temporary socket/channel grant linked to the current user token and exact signed handshake. Subscribe and each outgoing payload recheck token expiry/revocation, account/service/provider state and current conversation access. Failed checks unsubscribe and close the socket before sending the payload. A periodic loop additionally prunes idle invalid sockets (default5 seconds; CHAT_AUTH_SOCKET_PRUNE_SECONDS, minimum1). DB failures fail closed for guarded delivery. The signature registry and account tables must be shared with the API process.
Client-originated websocket events are disabled; all durable chat messages go through the authenticated REST API. Websocket input is limited to120 events/minute/socket and excessive clients are terminated. The guard uses installed Reverb channel-manager APIs; keep Reverb pinned and rerun socket tests/live smoke before upgrades. It is single-server verified scope; clustering remains unverified. The generic package alone does not enforce post-subscription host revocation. See security and realtime.
Verification: php artisan test includes account roles/scope/login/logout/token hashing/disablement/throttle and existing-socket revocation/expiry tests. Real WebSocket, production deployment and backup/restore evidence is recorded in project status separately.
Local real-socket smoke: from repository root with API/queue/Reverb running, execute pwsh -File examples/laravel-api/tests/smoke/socket-revocation.ps1. It uses local seeded fixtures, creates a labelled verification conversation, confirms authorized event delivery, logs out the subscribed customer, then verifies the socket closes without delivering a subsequent seller message. Repeat with -IdleOnly to confirm the periodic guard closes an idle revoked subscriber without any broadcast. It cleans up its tokens, prints no credentials and refuses non-loopback APIs. Forced low-level socket close can be reported by ClientWebSocket as an unclean close; that is counted as disconnect, not as a received chat payload.
Central console and integrations#
The role-aware sidebar and public guides are documented in admin console. Read-only management lists remain bounded to 200 rows; monitoring, audit and billing have server pagination. See console API and billing API.
Account responses now include is_external (boolean). External mapped accounts cannot use password login, even after an operator changes their password hash. Their management PATCH supports only name/is_active; email/password/role/provider/ service changes return 422. Session middleware and ongoing socket delivery check an issued token's source integration key for current service, expiry and revocation. See service key and identity contract.
Central-host provider/account creates and disabled-record reactivation check paid capacity under the same service row lock as billing changes. HTTP402 denies new capacity when payment/limits require attention. Global platform-admin accounts have no service capacity. Existing history, login, billing and allowed management edits remain available. These policies are not imposed on embedded package hosts.
Remembered website sessions#
Login accepts optional boolean remember (default false). The server issues a normal 480-minute token, or a 43200-minute (30-day) token when remembered. Configure these with CHAT_AUTH_TOKEN_LIFETIME_MINUTES and CHAT_AUTH_REMEMBER_LIFETIME_MINUTES on the API server; deploy the API before the updated frontend. No new table or migration is required. Scope rotation revokes the old token and preserves its original expiry; it does not renew login. Logout and existing account/provider/service revocation rules still apply.
The Next website saves only the user bearer token and UTC expiry in sessionStorage by default, or localStorage when Remember me is selected. The key is namespaced by the configured API root. It never stores passwords, service keys or cached role grants. On reload it calls GET /api/auth/me before showing protected workspace content. During verification a responsive, neutral workspace skeleton replaces the former full-page restore message; it contains no stored identity, role-dependent navigation, data or actions. The root session provider restores once per mount rather than on pathname changes, so client navigation between home, docs and workspace keeps the verified session. Storage events still verify replacement credentials, the expiry timer still clears expired sessions, and protected APIs remain authoritative on each request. A network failure offers Retry connection without discarding the saved credential; HTTP 401 or expiry clears it. Storage failures allow an in-memory login with a visible notice. Logout clears matching saved credentials after server revocation; failed logout stays open for retry. Remembered tabs observe logout and token rotation through storage events. Changing scope saves the replacement credential.
Browser storage is accessible to scripts running on this origin: this is a bounded bearer-session policy, not an HttpOnly cookie or refresh-token system. Avoid untrusted scripts, maintain XSS protections, and use Remember me only on private devices. Clearing site data or browser privacy policies can remove login. An integrating Shope application owns its own credential storage policy; installing a chat package does not persist its users automatically.
Console business names#
Console users see Accounts and Merchants & teams; API paths retain /admin/accounts and /admin/providers. Services remain connected applications. Platform-account creation/editing has no service/provider assignment. See the role and ownership guide for current menus.