Docs / RivetMSP / Reference
RivetMSP architecture
The admin, agent, client and guest portals, auth and permission model, data model, module toggles and integrations.
Overview#
RivetMSP is a single-tenant PHP MSP (managed service provider) platform: one install serves one MSP company, which in turn manages many clients (the MSP's own customers). There is no framework — it's hand-written PHP with mysqli and raw SQL throughout, organized as a set of top-level directories that map directly to URL paths. One MySQL database backs everything.
The codebase is best understood as four cooperating "portals" sharing a common core:
admin/— company configuration, user/role management, integrations, billing setup, database migrationsagent/— the day-to-day working UI for MSP technicians/staff (tickets, clients, assets, billing, RMM)client/— a self-service portal for the MSP's own customers (the end clients' contacts)guest/— unauthenticated, token-linked pages (approve a quote, pay an invoice, sign a document)
Shared infrastructure lives in includes/ (session/auth chain, permission functions, integration clients, global settings), functions.php (a large grab-bag of app-wide helper functions), cron/ (background jobs), and api/v1/ (the REST API, separately authenticated from the web portals).
A related, closed-source fork called RivetMSP Internal IT repurposes this same codebase for internal IT departments (renames Client to Department, disables billing/CRM by default, adds directory-sync and other features); its internals are out of scope for this document.
The Four Portals#
| Directory | Audience | Bootstrap include | Auth gate |
|---|---|---|---|
agent/ |
MSP technicians/staff | agent/includes/inc_all.php |
Logged-in users row, user_type = 1 |
admin/ |
Agents who also hold an admin role | admin/includes/inc_all_admin.php |
Same login as agent, plus $session_is_admin true |
client/ |
End-customer contacts | client/includes/inc_all.php |
Separate client_logged_in session, users row user_type = 2 joined to a contacts row |
guest/ |
Anyone with an emailed link | guest/includes/inc_all_guest.php |
Per-record random token in the URL (*_url_key / item_key columns) — no session at all |
Important: admin is not a distinct account type. There is no separate admin/login.php. An "admin" is simply an agent account (user_type = 1) whose role has role_is_admin = 1; admin/includes/inc_all_admin.php runs the identical agent login chain and then adds one extra check for $session_is_admin.
A naming trap to be aware of: agent/includes/inc_all_client.php is not the client-portal bootstrap. It's the bootstrap for "client overview" pages inside the agent portal — i.e., a technician viewing one client record — and enforces agent-side permissions (enforceUserPermission('module_client'), enforceClientAccess()). The actual client-portal login gate lives in client/includes/check_login.php.
Root index.php is the traffic cop for /: if $_SESSION['logged'] is set it redirects to the agent portal, else if $_SESSION['client_logged_in'] is set it redirects to client/, else to /login.php. Agent and admin share one session flag (logged); client uses a different one (client_logged_in) — both are possible in the same PHP session namespace but are mutually exclusive per login.
Authentication & Sessions#
Agent / admin login#
There is a single root-level login.php handling both agent and client logins against one users table, keyed by email + password. It's a small state machine:
- Credentials — looks up
users(joined touser_settings,contacts,clients) by email andpassword_verify()s against every matchinguser_typerow (at most oneuser_type=1and oneuser_type=2row can share an email). - Role choice (dual-role accounts only) — if the same email verifies against both an agent row and a client row, the user picks which to sign into, tracked by a short-lived
$_SESSION['pending_dual_login']. - MFA (agent only, if TOTP is enrolled) — a
$_SESSION['pending_mfa_login']pending state gates a TOTP check.
Agent authentication factors:
- Password —
password_verify()againstusers.user_password(Argon2id since DB 2.6.79; older bcrypt hashes verify and are replaced at the next sign-in). Staff password rules:includes/security_policy.php. - TOTP 2FA —
plugins/totp/totp.php; the secret isusers.user_token, stored wrapped byencryptSetting()(ENC2:); read it throughsecUserTotpSecret(). Ten single-use recovery codes (user_recovery_codes, hashed) can replace the code at sign-in. Required per user viauser_settings.user_config_force_mfaor for everyone / administrators via the Sign-in policy (security_settings.mfa_policy);secMfaGate()inincludes/check_login.phpconfines an unenrolled, out-of-grace agent toagent/user/*. - WebAuthn / passkeys — a separate flow outside
login.php(passkey_auth_begin.php,passkey_auth_complete.php, driven byincludes/webauthn.phpandjs/webauthn_signin.js). Hard-restricted touser_type = 1— client contacts cannot use passkeys. A passkey is treated as sufficient on its own and bypasses TOTP. - Optional shared "login key" —
settings.config_login_key_required/config_login_key_secret, an install-wide perimeter secret checked independently of the user's own credentials. - Remember-me — a hashed cookie in
remember_tokens(agent-only) that bypasses 2FA at login and silently re-establishes a session on later visits ("internet outages don't force re-login"). It is refused for an administrator or a user with vault access who has MFA unless the Sign-in policy allows it.
On success, login.php sets exactly:
$_SESSION['user_id'] = $user_id;
$_SESSION['csrf_token'] = randomString(32);
$_SESSION['logged'] = true;
session_regenerate_id(true);
secSessionStart() then records the idle / absolute clocks and a user_sessions row (includes/security_sessions.php; the idle timeout is security_settings.session_idle_minutes, the absolute maximum settings.config_login_session_lifetime), and includes/auth_check.php enforces both and revocation on every request. That is the entire session contract. Everything else — name, role, admin flag, permissions — is re-derived per request, not cached in the session, by the include chain below.
The includes/check_login.php chain#
Every agent/admin page runs this orchestrator, which in turn requires:
includes/session_init.php— starts the session withhttponly/securecookies, strict mode andSameSite=Lax, the cookie lifetime being the absolute session maximum (settings.config_login_session_lifetime, default 7 days, clamped 60 min–90 days;secSessionIniApply()inincludes/security_sessions.php). The idle timeout (default 8 h) is enforced per request byincludes/auth_check.php.includes/auth_check.php— the actual gate. If$_SESSION['logged']isn't set, tries to auto-restore from theremembermecookie (rotating the token, single-use); otherwise redirects to/login.php.includes/load_user_session.php— the important one. Re-verifiesuser_type === 1,user_status === 1, and not archived (killing a disabled/archived user's session on their very next request), and sets the request-scoped globals nearly everything else depends on:$session_user_role—users.user_role_id$session_is_admin— derived from the joineduser_roles.role_is_admincolumn; the single source of truth for admin-ness$client_access_array/$client_access_string/$access_permission_query— per-user client scoping (see below)
includes/load_company_settings.php/includes/load_global_settings.php— load the singletonsettings/companiesrows into globals shared by all four portals (module toggles, numbering sequences, SMTP config, etc.).
Client portal login#
Client-portal identity is not a separate table — it reuses users with user_type = 2, 1:1-linked to a contacts row via contacts.contact_user_id. Portal access is granted explicitly: when an agent creates/edits a contact with login credentials (agent/post/contact.php), both a users row and the linking contacts.contact_user_id are written together. A contacts row with no linked users row simply has no portal login.
Client logins go through the same login.php STEP 1 password check (one shared email field for both account types). The client branch additionally:
- Checks
settings.config_client_portal_enable— if the portal is disabled company-wide, login is refused even with a correct password. - Requires
user_auth_method === 'local'; SSO users go throughclient/login_microsoft.phpinstead (Microsoft Entra ID OAuth2, described under Integrations).
On success it sets client_logged_in, client_id, user_id, user_type = 2, contact_id, and (for shared-check convenience) logged = true as well.
Per-request, client/includes/check_login.php re-derives everything from the session, re-verifies user_type === 2 / active / not archived against the DB (duplicating the agent-side pattern rather than sharing code), and loads three boolean flags off the contact's own row — contact_technical, contact_billing, contact_primary — which are the entire client-portal permission model (see below). No TOTP/WebAuthn option exists for client contacts.
Guest portal#
guest/includes/inc_all_guest.php has no login/session-identity include at all. It sets its own security headers (CSP, X-Frame-Options: DENY, etc.) since it's the unauthenticated surface, and individual pages resolve their target record from a random per-record token in the URL rather than any user identity.
Permission Model#
There are, in effect, three separate, independently-evolved layers, worth keeping distinct rather than conflating:
1. Module + role-based permissions (agent/admin, the live system)#
Schema: modules (a small fixed catalog — module_client, module_support, module_credential, module_sales, module_financial, module_reporting, module_kb, and others referenced in code such as module_rmm), user_roles (role_id, role_name, role_is_admin), user_role_permissions (user_role_id + module_id → an access level), users.user_role_id.
Core functions in functions.php:
lookupUserPermission($module)— returns an access level 1 (read) / 2 (write) / 3 (full), orfalse. Admins ($session_is_admin) always get 3, bypassing the table entirely.enforceUserPermission($module, $check_access_level = 1)— a hardexit()(not a redirect) if the level isn't met. Used both defensively at the top of write handlers and to conditionally show/hide nav/UI.
Roles are managed at admin/roles.php (admin-only).
2. Module enable toggles — a separate axis (company-wide, not per-user)#
Boolean columns on the singleton settings row, loaded once per request into globals like $config_module_enable_kb, $config_module_enable_accounting, $config_module_enable_rmm, $config_client_portal_enable, etc. (full list under "Module / Feature Toggles" below). These answer "does this feature exist for this install at all", independent of who's allowed to use it. Nav code typically ANDs both axes together, e.g. a knowledge-base link only shows when the KB module is both enabled and the current role has read permission on module_kb.
3. Per-client scoping (user_client_permissions)#
Schema: user_client_permissions(user_id, client_id) — a simple allow-list.
Two independent consumers:
- Read-side / list filtering:
$access_permission_query(built inload_user_session.php) is spliced directly into raw SQL across roughly ninety files (client lists, ticket lists, most reports and modals) asAND clients.client_id IN (...). - Write-side / single-record guard:
enforceClientAccess($client_id)infunctions.php.
The nuance worth internalizing: this is allow-list, but only activates once at least one row exists for that user. A non-admin user with zero user_client_permissions rows can see/touch every client (unrestricted default); adding even one row switches that user into a strict allow-list containing only the listed clients. It's easy to misread "empty" as "deny" — it means the opposite.
4. Client-portal permissions (much simpler)#
Client contacts have no modules/roles at all. Visibility inside client/ is driven purely by three booleans loaded off the contact's own row: contact_primary, contact_billing (technical/asset/ticket-adjacent), contact_technical. The primary contact for a client implicitly gets both billing and technical visibility. These combine with the same company-wide config_module_enable_* toggles used elsewhere.
5. Legacy dead-ish code (flagged, not the real model)#
functions.php still defines validateAdminRole() / validateTechRole() / validateAccountantRole(), explicitly commented as legacy (comparing a flat role int against hard-coded 1/2/3), predating the modules/user_role_permissions system. Only a couple of call sites remain in the whole tree (admin/post/update.php, agent/custom/index.php). Treat this as vestigial, not as the current permission model.
Session/identity variables at a glance#
| Variable | Set where | Meaning |
|---|---|---|
$_SESSION['logged'] |
login.php (agent path), passkey completion, remember-me restore |
agent/admin session exists |
$_SESSION['client_logged_in'] |
login.php (client path) |
client-portal session exists |
$session_is_admin |
includes/load_user_session.php, per-request from user_roles.role_is_admin |
admin gate + permission bypass |
$session_user_role |
includes/load_user_session.php |
users.user_role_id, the permission lookup key |
$client_access_string / $access_permission_query |
includes/load_user_session.php |
per-user client scoping, spliced into SQL app-wide |
$session_contact_is_technical_contact / _is_billing_contact / $session_contact_primary |
client/includes/check_login.php |
client-portal's entire visibility model |
Data Model#
RivetMSP is single-tenant per install — one companies row (company_id = 1, the MSP's own org profile), entirely separate from clients (the MSP's customers, the hub everything else hangs off).
The dominant relational convention is naming, not database-enforced foreign keys: child tables carry an int NOT NULL DEFAULT 0 column named <entity>_client_id, <entity>_ticket_id, etc., and the application joins on it in code. Most core tables (clients, contacts, locations, tickets, ticket_replies, assets, credentials, invoices, quotes) declare no FOREIGN KEY constraint — contracts is the one notable exception, with a real FK to clients. By contrast, small many-to-many/join/tag tables (asset_credentials, contact_tags, client_tags, calendar_event_attendees, etc.) do use real FKs with ON DELETE CASCADE. In short: core "belongs-to" relationships are an app-code convention; join/pivot tables are database-enforced.
Central entities, in prose form:
clients— the root.client_idPK; everything else references it via*_client_id.contacts— belongs to a client; optionally linked to ausersrow (contact_user_id) for portal login; carries thecontact_primary/contact_billing/contact_technicalrole flags used by the client portal's permission model.locations— belongs to a client, with an optional site contact.contracts— belongs to a client (real FK); carries per-priority SLA response/resolution times and included support-hours allowances, feeding SLA due-date computation on tickets.tickets— the join point for nearly everything: links to client, contact, location, asset, contract, quote, invoice, project, vendor. Scheduling/appointment fields (ticket_schedule,ticket_onsite, etc.) live directly on the ticket row — there is no separate appointments table. SLA due timestamps are computed from the linked contract.ticket_replies— ticket conversation/work-log entries, including time-worked.ticket_charges— per-ticket billable line items (product/labor/tax/quantity), distinct from the general-ledger accounting tables; swept into invoices viacharge_invoiced_at.ticket_worksheets/ticket_worksheet_responsesand a separateticket_outtake_formstable both support ticket sign-off/signature capture with overlapping purposes; which is the fully "live" path was not conclusively determined from static inspection alone.assets— belongs to a client, with optional location/contact/vendor, hardware fields, and RMM/warranty metadata.credentials— belongs to a client, with optional links to a contact/asset/vendor/software/folder; the password column is encrypted at rest, with an OTP secret field for stored TOTP.invoices/invoice_items,quotes(parallel shape),recurring_invoices(cron-driven generation),payments,expenses— the accounting/billing surface.kb_articles/kb_categories— a client id of 0 means a company-wide article; a full-text index supports search.projects— belongs to a client, with a per-install numbering sequence; tickets can optionally belong to a project.
Other notable tables not detailed above: recurring_tickets, ticket_automation_rules/ticket_automation_runs, ticket_watchers, per-entity audit-trail tables (ticket_history, asset_history, credential_history, domain_history, certificate_history), networks/racks/rack_units, domains/certificates, vendors, software/software_keys, plus the RMM (rmm_*, 7 tables) and UniFi (unifi_*, 3 tables) integration tables.
Module / Feature Toggle System#
Feature availability is controlled at two independent layers, and it's worth keeping them distinct when reading nav/gating code:
-
Company-wide enable toggles — boolean columns on the singleton
settingsrow, loaded once per request byincludes/load_global_settings.phpinto globals such as:Global Gates $config_module_enable_itdocIT documentation (assets/credentials/etc.) $config_module_enable_ticketingTicketing throughout the app $config_module_enable_accountingFull invoicing/quotes/recurring-invoices/expenses $config_module_enable_ticket_chargesBillable time/charges on tickets, usable independently of full accounting $config_module_enable_kbKnowledge base (agent and client) $config_module_enable_live_chatReal-time ticket chat $config_module_enable_payrollPayroll (gross-pay only, no tax withholding); admin-only nav $config_module_enable_rmmRMM integration UI, toggled from the integrations settings page rather than the generic modules page $config_module_enable_unifiUniFi integration $config_client_portal_enableWhether the client portal accepts logins at all Managed mainly at
admin/settings_module.php; RMM has its own settings screen. -
Per-role module permissions — the
modules/user_role_permissions/user_rolessystem described under Permissions, answering "can this role see it" rather than "does this feature exist."
Nav code typically requires both: the feature must be turned on for the install and the current role must hold at least read access on the corresponding permission module. CRM and Projects have no company-wide enable toggle at all — they're always-on core features, gated only by role permissions.
Database Migrations#
includes/database_version.php defines LATEST_DATABASE_VERSION (a semantic-ish version string). Each install's current version is stored in settings.config_current_database_version.
admin/database_updates.php is a flat sequence of blocks shaped like:
if (CURRENT_DATABASE_VERSION == '2.6.48') {
// ALTER/CREATE TABLE statements for this one step
mysqli_query($mysqli, "UPDATE `settings` SET `config_current_database_version` = '2.6.49'");
}
Because the version is a PHP constant fixed once per request and the blocks are plain if (not a loop), exactly one version step advances per page load. The admin UI (admin/update.php) re-shows its "Update Database" button as long as a newer version exists, so upgrading across many versions means clicking it repeatedly; there's a CLI equivalent (scripts/update_cli.php --update_db) with the same one-step-per-invocation behavior. Migration blocks increasingly use IF NOT EXISTS guards for idempotency.
A discrepancy worth knowing about: db.sql (the fresh-install schema dump) is not a clean snapshot of any single point in this migration chain — it is missing some features added by earlier migrations (notably the entire Payroll table set, and some newer settings/CSAT columns) while containing at least one column from a later migration. Since a fresh install loads db.sql and then stamps itself as already fully current without running database_updates.php, a new install can end up permanently missing tables/columns that the migration chain would otherwise have backfilled. Treat db.sql as broadly representative of the schema, but don't assume it's authoritative for every recently-added feature — check database_updates.php for anything payroll- or CSAT-adjacent, or anything else suspected to be recent.
REST API#
api/v1/index.php is a flat, single-router REST API dispatcher, entirely separate from the session-cookie auth used by the four portals above. It supports two independent auth mechanisms — per-user Bearer tokens (api_tokens, the primary/current mechanism, usable by both agent- and client-type users) and a legacy company-wide X-Api-Key (api_keys, with its own read/write permission level and optional single-client scoping). It also serves a self-documenting OpenAPI spec at /api/v1/openapi.yaml. Per project history there is a second, dead legacy API implementation elsewhere in the tree that is not the live one. Full endpoint-by-endpoint reference lives in docs/API.md — this section intentionally does not duplicate it.
Integrations#
- RMM (Remote Monitoring & Management) — a factory/abstraction (
includes/rmm_client_factory.php) dispatches to one of four provider clients based onrmm_integrations.type: Tactical RMM, Level.io, Action1 (OAuth2 patch management), and Sophos Central (OAuth2, scoped to firewall inventory/alerts).includes/class_rmm_asset_mapper.phpmatches RMM agents to RivetMSPassets(by linked ID, then serial, MAC, hostname) and syncs alerts. Sync runs on every cron cycle fromcron/cron.php, and can auto-create tickets from severity-gated alerts. - RMM module (built-in endpoint agent) — an optional, default-OFF RivetCore module (
RivetCore\Rmm) wired byincludes/rmm_bootstrap.phpandsrc/Core/Adapter/Endpoint/: device and technician REST endpoints, an admin page, a device page and a cron block. It is on only whensettings.config_core_rmm_enabledandendpoint_agent_settings.enabledare both on; while off,api/v1/rmm_gate.phpanswers agents with 503 from a state file with no database work. Seedocs/RMM_MODULE.md. - UniFi networking — a local-controller client and a cloud-controller client, mapped into RivetMSP
assets/credentials/networksbyincludes/class_unifi_sync_mapper.php. Notably, this sync runs from a standalone script (scripts/unifi_sync_cli.php), not wired into the maincron/cron.phpdispatcher — it needs its own separately configured cron entry. - QuickBooks Online (accounting) — one-way push only (RivetMSP → QBO, never back).
includes/class_qbo_client.phphandles OAuth2 token refresh and Customer/Item/Invoice/Payment sync. A queue (accounting_sync_queue) is drained bycron/accounting_sync.phpwith exponential backoff and dependency ordering (customer before invoice, invoice before payment), with idempotency guaranteed via anaccounting_entity_maptable. - Stripe (payments) — behind a generic
PaymentProviderInterface/factory (designed for future additional gateways), currently implemented only byincludes/class_stripe_payment_provider.php. Used for guest invoice payment, webhooks, client-portal saved cards, and agent-recorded payments. - Microsoft Entra ID (client portal SSO) — OAuth2 authorization-code flow (
client/login_microsoft.php) plus a Microsoft Graph/mecall for profile info at login time. This is login-only — no broader directory sync was found. Microsoft OAuth is used separately for mailbox connections (below); no Odoo integration exists anywhere in the codebase. - Email — inbound:
cron/ticket_email_parser.phppolls configured mailboxes via IMAP (Webklex library, with OAuth2 support for Microsoft 365/Google Workspace) to create/update tickets from incoming mail. Outbound:cron/mail_queue.phpdrains an app-wide mail queue via PHPMailer (SMTP or OAuth token-based sending); enqueued app-wide viaaddToMailQueue()infunctions.php. - Real-time (SSE + push) — Server-Sent Events backed by Redis pub/sub power live ticket updates, live ticket chat (for API/mobile clients), and live in-app notifications. Firebase Cloud Messaging (
includes/firebase.php, hand-rolled JWT/OAuth exchange) delivers push notifications to mobile devices. In-app notifications are created byappNotify()(every active technician) andnotifyUser()(one user) infunctions.php; each user can switch whole categories off on Account > Preferences (includes/notification_categories.php,user_settings.user_config_inapp_muted_types), and a muted category is never stored, published or pushed for that user. Security notices and RMM alert escalations cannot be switched off.
Background jobs (cron/)#
All are standalone-runnable PHP CLI scripts, most also require_once'd from the umbrella cron/cron.php dispatcher on an admin-configurable schedule (admin/cron.php):
| File | Purpose |
|---|---|
cron/cron.php |
Main dispatcher — recurring tickets/invoices/expenses, backups, ticket-automation rules, RMM sync + auto-ticketing; the RivetMSP release check runs once a day at 03:00 app time (includes/update_check_schedule.php), not on every run |
cron/mail_queue.php |
Outbound email delivery |
cron/ticket_email_parser.php |
Inbound IMAP mail to tickets |
cron/accounting_sync.php (+ accounting_sync_standalone.php) |
QuickBooks push queue worker |
cron/crm_reminders.php |
Due CRM activity reminder notifications |
cron/certificate_refresher.php |
SSL certificate monitoring refresh |
cron/domain_refresher.php |
Domain WHOIS/expiry monitoring refresh |
cron/metrics_rollup.php |
Daily ticket-flow metrics snapshot for dashboards |
cron/outlook_schedule_sync.php |
Pull-direction half of two-way Outlook calendar sync |
cron/report_scheduler.php |
Scheduled report emails |
scripts/unifi_sync_cli.php is the one notable exception — it is not included from cron/cron.php and needs its own separately configured cron entry.
Editions#
This document covers RivetMSP, the MSP platform built on upstream ITFlow. Its sibling RivetIT serves internal IT departments, with department terminology and different default modules. RivetIT internals are outside this document’s scope.
docs/ARCHITECTURE.md in the RivetMSP repository.
View or edit on GitHub