Skip to content
Docs

Backend API and api-models

Identity Manager (identity-manager)

Section titled “Identity Manager (identity-manager)”

Identity Manager is the Sylva backend: REST API, authentication, billing hooks, email, SSO flows, and operational endpoints. It is a LoopBack 2 application (loopback, loopback-boot) on Node.js 12 (see package.json engines in the repo).

Entry point: server/server.js — standard LoopBack bootstrapping, CORS, body limits, EJS views, favicon, then loopback-boot loads server/ configuration.

Responsibilities (high level)

Section titled “Responsibilities (high level)”
  • CRUD and remote methods for SystemUser, Organization, Project, modules, files, seats, invitations, etc. (see API reference).
  • Auth: login/logout, JWT/session patterns, Firebase custom tokens, org access checks (/SystemUsers/{id}/fbAuthToken/{organizationId}, checkOrgAccess, …).
  • Integrations: Stripe (seats, invoices), SendGrid/Twilio (email/SMS), SAML/OIDC (Passport), GCP (Storage, Pub/Sub, Cloud Tasks, BigQuery clients in dependencies).
  • Views: password reset, magic link, SSO confirmation — rendered from server/views and email/views.

Configuration surfaces

Section titled “Configuration surfaces”
  • Environment: NODE_ENV, LOCAL, secrets for tokens, API keys, GCP credentials (typical for App Engine or VM deploys).
  • Model config: server/model-config.json and variants (development, beta, production, …) select datasources and model roots.
  • Datasources: MongoDB connection and any other connectors defined under server/datasources*.json.

CORS and cookies

Section titled “CORS and cookies”

server/server.js configures CORS with credentials; allowed origins are based on host patterns (e.g. sylva.ac, and localhost in non-production). Cookie parsing uses a per-request secret derived from user agent and TOKEN_SECRET. Large JSON bodies are allowed on /api/*, /sso/*, /v2/* for bulk editor payloads.

api-models (shared models)

Section titled “api-models (shared models)”

api-models is the single source of truth for LoopBack model JSON (*.json) and model JavaScript (hooks, remote methods, validations) that define the Sylva API surface.

From package.json:

  • "description": "This is all the model definitions for all the SYLVA APIs"
  • "keywords": ["loopback", "api", "model", "sylva"]

It is not published as a standalone HTTP server ("main": "no-entry"). You do not npm start api-models in production.

Relationship to Identity Manager

Section titled “Relationship to Identity Manager”

Identity Manager’s server/model-config.json includes model roots such as:

  • loopback/common/models (framework)
  • ../common/models — this is the api-models checkout

The repo uses a git submodule (see .gitmodules in identity-manager) pointing at github.com/sylva-ag/api-models.git. In a full clone you will have identity-manager/common/models populated from that submodule.

What lives in api-models

Section titled “What lives in api-models”

Typical layout (illustrative):

  • JSON models: e.g. project.json, system-user.json, organization.json — properties, relations, ACLs.
  • Per-model JS: project/methods/*.js, system-user/methods/*.js — remote methods and helpers.
  • Cross-cutting: CONFIG/ (Firebase, roles, helpers), email/ templates, worker/ methods that back /Worker/* routes.

CHANGELOG.md in api-models records semver releases; treat breaking API or schema changes like any other API rollout.

Developer workflow for API changes

Section titled “Developer workflow for API changes”
  1. Edit models/methods in api-models (or a branch).
  2. Run Identity Manager locally against a dev database with common/models pointing at your branch (submodule pointer or symlink in dev only—never commit ad-hoc symlinks unless your team allows it).
  3. Exercise endpoints via Sylva Enterprise or Postman; update this docs site API reference if you add or rename public contracts.
  4. Tag/release api-models; update the submodule commit in identity-manager; deploy Identity Manager.

Worker endpoints vs sylva-worker repo

Section titled “Worker endpoints vs sylva-worker repo”

LoopBack exposes a Worker model with only remote methods (no generic CRUD)—for example cleanup and analytics hooks (see API reference Worker section). Long-running or specialized workloads may also live in the separate sylva-worker repository (see Background jobs and workers). Both are “workers” in the broad sense; the code location depends on the feature’s history and hosting model.