Skip to content

Enterprise API

The Enterprise API is the dedicated client-facing surface for commercial facility managers, enterprise estate clients, and property partners.

While Vibrant staff and field technicians perform walkthroughs, set schedules, and triage issues via the Internal API, the Enterprise API provides the external client portal for property owners and managers to monitor operations and approve work.

What It Does

  • Client Maintenance Calendar & Assets: Viewing property equipment, maintenance schedules, and completed service records.
  • Walkthrough & Media Inspection: Reviewing inspection reports, walkthrough summaries, and photo/video evidence.
  • Work Item Decisions & Approvals: Reviewing recommended repairs and recording client approval decisions (accept, defer, decline).
  • Media Storage Integrations: Generating presigned URLs for client uploads/downloads (S3/RustFS) and receiving async object-creation webhooks.

The Dual-Transport Split

Like the other surfaces, the Enterprise API splits read queries from stateful workflows:

  1. Enterprise PostgREST (enterprise_api schema, port 3850):
  2. Handles high-volume reads directly from PostgreSQL views: maintenance schedules, assets, walkthrough logs, and work items.
  3. Enforces Row-Level Security (RLS) scoped to the caller's authorized company and sites.
  4. Enterprise FastAPI (vibrant_platform_enterprise_api, port 3800):
  5. Handles multi-step operations: POST /sites/{site_id}/media/upload-intents, GET /sites/{site_id}/media/{media_id}/download, and POST /sites/{site_id}/work-items/{item_id}/decision.
  6. Ingests asynchronous object-storage webhooks at /internal/media/object-created via shared webhook tokens.

Identity & Authorization

  • Keycloak Client: vibrant-enterprise-web in the vibrant realm.
  • JWT Claim: Carries role: enterprise_portal_role.
  • Anonymous Access: Falls back to enterprise_portal_anon (fails closed for protected resources).
  • Database Connection: FastAPI connects via enterprise_api_login using application role enterprise_api_role.
  • Shared Code: Imports shared database and security utilities from vibrant_platform_common, but never imports from vibrant_platform_api or vibrant_platform_internal_api.

Technical Pointers

  • Service Code: src/vibrant_platform_enterprise_api/
  • Entrypoint: vibrant_platform_enterprise_api.main:create_app
  • Settings: src/vibrant_platform_enterprise_api/app_settings.py (VIBRANT_ENTERPRISE_API_*)
  • Database Schemas: enterprise_api, site_maintenance, and media in infrastructure/db/schema.sql
  • Local Compose Service: enterprise-api and enterprise-postgrest in infrastructure/local/compose.yaml