Skip to content

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 migrations
  • agent/ — 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:

  1. Credentials — looks up users (joined to user_settings, contacts, clients) by email and password_verify()s against every matching user_type row (at most one user_type=1 and one user_type=2 row can share an email).
  2. 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'].
  3. MFA (agent only, if TOTP is enrolled) — a $_SESSION['pending_mfa_login'] pending state gates a TOTP check.

Agent authentication factors:

  • Password — password_verify() against users.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 is users.user_token, stored wrapped by encryptSetting() (ENC2:); read it through secUserTotpSecret(). Ten single-use recovery codes (user_recovery_codes, hashed) can replace the code at sign-in. Required per user via user_settings.user_config_force_mfa or for everyone / administrators via the Sign-in policy (security_settings.mfa_policy); secMfaGate() in includes/check_login.php confines an unenrolled, out-of-grace agent to agent/user/*.
  • WebAuthn / passkeys — a separate flow outside login.php (passkey_auth_begin.php, passkey_auth_complete.php, driven by includes/webauthn.php and js/webauthn_signin.js). Hard-restricted to user_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 with httponly/secure cookies, strict mode and SameSite=Lax, the cookie lifetime being the absolute session maximum (settings.config_login_session_lifetime, default 7 days, clamped 60 min–90 days; secSessionIniApply() in includes/security_sessions.php). The idle timeout (default 8 h) is enforced per request by includes/auth_check.php.
  • includes/auth_check.php — the actual gate. If $_SESSION['logged'] isn't set, tries to auto-restore from the rememberme cookie (rotating the token, single-use); otherwise redirects to /login.php.
  • includes/load_user_session.php — the important one. Re-verifies user_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 joined user_roles.role_is_admin column; 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 singleton settings/companies rows 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 through client/login_microsoft.php instead (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), or false. Admins ($session_is_admin) always get 3, bypassing the table entirely.
  • enforceUserPermission($module, $check_access_level = 1) — a hard exit() (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 in load_user_session.php) is spliced directly into raw SQL across roughly ninety files (client lists, ticket lists, most reports and modals) as AND clients.client_id IN (...).
  • Write-side / single-record guard: enforceClientAccess($client_id) in functions.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_id PK; everything else references it via *_client_id.
  • contacts — belongs to a client; optionally linked to a users row (contact_user_id) for portal login; carries the contact_primary/contact_billing/contact_technical role 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 via charge_invoiced_at.
  • ticket_worksheets / ticket_worksheet_responses and a separate ticket_outtake_forms table 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:

  1. Company-wide enable toggles — boolean columns on the singleton settings row, loaded once per request by includes/load_global_settings.php into globals such as:

    Global Gates
    $config_module_enable_itdoc IT documentation (assets/credentials/etc.)
    $config_module_enable_ticketing Ticketing throughout the app
    $config_module_enable_accounting Full invoicing/quotes/recurring-invoices/expenses
    $config_module_enable_ticket_charges Billable time/charges on tickets, usable independently of full accounting
    $config_module_enable_kb Knowledge base (agent and client)
    $config_module_enable_live_chat Real-time ticket chat
    $config_module_enable_payroll Payroll (gross-pay only, no tax withholding); admin-only nav
    $config_module_enable_rmm RMM integration UI, toggled from the integrations settings page rather than the generic modules page
    $config_module_enable_unifi UniFi integration
    $config_client_portal_enable Whether the client portal accepts logins at all

    Managed mainly at admin/settings_module.php; RMM has its own settings screen.

  2. Per-role module permissions — the modules/user_role_permissions/user_roles system 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 on rmm_integrations.type: Tactical RMM, Level.io, Action1 (OAuth2 patch management), and Sophos Central (OAuth2, scoped to firewall inventory/alerts). includes/class_rmm_asset_mapper.php matches RMM agents to RivetMSP assets (by linked ID, then serial, MAC, hostname) and syncs alerts. Sync runs on every cron cycle from cron/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 by includes/rmm_bootstrap.php and src/Core/Adapter/Endpoint/: device and technician REST endpoints, an admin page, a device page and a cron block. It is on only when settings.config_core_rmm_enabled and endpoint_agent_settings.enabled are both on; while off, api/v1/rmm_gate.php answers agents with 503 from a state file with no database work. See docs/RMM_MODULE.md.
  • UniFi networking — a local-controller client and a cloud-controller client, mapped into RivetMSP assets/credentials/networks by includes/class_unifi_sync_mapper.php. Notably, this sync runs from a standalone script (scripts/unifi_sync_cli.php), not wired into the main cron/cron.php dispatcher — it needs its own separately configured cron entry.
  • QuickBooks Online (accounting) — one-way push only (RivetMSP → QBO, never back). includes/class_qbo_client.php handles OAuth2 token refresh and Customer/Item/Invoice/Payment sync. A queue (accounting_sync_queue) is drained by cron/accounting_sync.php with exponential backoff and dependency ordering (customer before invoice, invoice before payment), with idempotency guaranteed via an accounting_entity_map table.
  • Stripe (payments) — behind a generic PaymentProviderInterface/factory (designed for future additional gateways), currently implemented only by includes/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 /me call 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.php polls 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.php drains an app-wide mail queue via PHPMailer (SMTP or OAuth token-based sending); enqueued app-wide via addToMailQueue() in functions.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 by appNotify() (every active technician) and notifyUser() (one user) in functions.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.

This page is rendered from docs/ARCHITECTURE.md in the RivetMSP repository. View or edit on GitHub