Skip to content

Two Way PSA and REST API

Jump to bottom
Tyler Hatfield edited this page Nov 12, 2026 · 4 revisions

Two-Way PSA Synchronization & REST API Reference (v2.5.1)

Vitrine RMM provides bidirectional ticketing synchronization with ITFlow, authenticated webhook ingestion, and a comprehensive session-authenticated REST & WebSocket API.

1. Bidirectional PSA Ticket Synchronization

  • Ticket Lifecycle (GET, POST, PUT /api/psa/tickets): Create service tickets directly from Vitrine, automatically open incident tickets from Policy Condition Alert Rules (createTicket: true) or tripped Self-Healing Watchdogs, and synchronize status changes bidirectionally with ITFlow (POST /api/psa/sync, protected by validateOutboundHostSafety()).
  • Authenticated Webhook Ingestion (POST /api/psa/webhook): Verifies X-Vitrine-Webhook-Secret / HMAC-SHA256 signature (psa_webhook_secret, stored encrypted in the AES-256-GCM vault) using constant-time comparison before applying inbound ticket updates.

2. Core v2.5.1 REST & WebSocket API Reference

All /api/* endpoints (except /api/health, /api/public/portal-config, /api/auth/status, /api/auth/setup-initial-admin, /api/auth/login, /api/auth/oidc/login, /api/auth/oidc/callback, token-gated /api/agent/*, and /api/guest-portal/*) require an authenticated vitrine_session cookie or Authorization: Bearer <token> header.

  • Authentication, Enterprise OIDC PKCE SSO, RBAC & Step-Up MFA:
    • GET /api/auth/status — Check bootstrap status, OIDC SSO availability, and active user session.
    • POST /api/auth/setup-initial-admin — One-time initial super_admin bootstrap (locks with 409 once initialized).
    • POST /api/auth/login & POST /api/auth/logout — Scrypt password login & session revocation.
    • GET /api/auth/oidc/login, GET /api/auth/oidc/callback, POST /api/auth/oidc/test — OpenID Connect Authorization Code + S256 PKCE SSO login, callback validation, and admin discovery tester.
    • POST /api/auth/verify-mfa — Per-user Step-Up RFC 6238 TOTP / single-use recovery code verification (anti-replay enforced).
    • GET /api/users, POST /api/users, PUT /api/users/:id, DELETE /api/users/:id — Multi-tenant RBAC user management (super_admin only; protects last super_admin and revokes sessions on credential/role change).
  • Fleet, Vault Secrets, Custom Fields & LAPS:
    • GET /api/devices & GET /api/devices/:id — Tenant-scoped endpoint inventory (bitlocker_key stripped; laps: null for client_admin).
    • GET /api/devices/:id/bitlocker — Step-Up MFA-gated BitLocker/LUKS/FileVault recovery key reveal.
    • GET /api/devices/:id/laps?reveal=true & POST /api/devices/:id/laps/rotate — MFA-gated LAPS password reveal & offline-safe rotation.
    • GET /api/devices/:id/custom-fields?reveal=true & PUT /api/devices/:id/custom-fields — Tenant-scoped custom attributes with AES-256-GCM encryption & Step-Up MFA reveal for secret fields.
    • POST /api/laps/break-glass-export — Super-Admin + Step-Up MFA emergency LAPS vault export.
  • Offboarding & Data Archive Vault:
    • POST /api/devices/:id/offboard & POST /api/devices/:id/force-archive — Clean online offboard or offline pending queue / immediate Archive Vault transition.
    • POST /api/tenants/:id/offboard & POST /api/tenants/:id/reactivate — Archive entire client in last-known state or permanently delete with Tombstone registration.
    • DELETE /api/devices/:id/archive-purge — Permanent Super-Admin purge of an archived endpoint.
  • Policies, Condition Alerts, Hypervisors & Specialty Endpoints:
    • GET /api/policies, POST /api/policies, PUT /api/policies/:id, GET /api/policies/effective/:deviceId — 4-tier cascading policy & alert matrix CRUD.
    • GET /api/notifications — Tenant-isolated UI notification feed (WHERE tenant_id = ? for client_admin).
    • GET /api/alerts/events & POST /api/alerts/evaluate — Condition notification ledger & on-demand evaluation.
    • GET /api/discovery/vendor-profiles, GET /api/discovery/appliances, POST /api/discovery/appliances, POST /api/discovery/appliances/:id/poll — Vendor-native specialty device monitoring.
    • GET /api/virtualization/hosts, POST /api/virtualization/hosts, POST /api/virtualization/hosts/:id/sync, POST /api/virtualization/hosts/:hostId/vms/:vmid/action — Live Proxmox VE / vSphere / Hyper-V inventory sync & VM power/snapshot dispatch.
  • Encrypted Backups, Recovery Key Escrow & Self-Updater (super_admin):
    • GET /api/backups, POST /api/backups, GET /api/backups/:id/download, POST /api/backups/:id/restore, POST /api/backups/upload-restore — VRMMENC1 encrypted backups & live atomic restore with reloadVaultMasterKey().
    • POST /api/backups/recovery-key & POST /api/backups/acknowledge-key — Step-Up MFA-gated Backup Encryption Recovery Key reveal/export & escrow reminder acknowledgment.
    • GET /api/updater/status, POST /api/updater/check, POST /api/updater/apply — stable / alpha full Git + build + auto-rollback self-updater.
  • Authenticated WebSockets:
    • /ws/telemetry — Origin-checked, live-revocation-verified real-time fleet CPU, RAM, and Network Mbps stream.
    • /ws/terminal — Origin-checked, live-revocation-verified (technician / super_admin + tenant-verified) background shell bridge.

3. Executive QBR & Fleet Health Report Generator

GET /api/reports/qbr computes live composite Fleet Health Index scores across endpoint availability, patch compliance, disk encryption coverage, EDR status, and self-healing hours saved — ready for one-click Executive PDF/Print export.

Clone this wiki locally