Website Integration Guide

Overview

Every school on CampusOS is free to run its own public marketing website, on its own domain, built however it likes. This guide is what to hand that website's developer — whether that's you, an agency, or the school's existing vendor — so their site can talk to CampusOS directly: a real login that lands a parent or staff member already signed in, a real admission enquiry that lands in the school's actual Admission Pipeline, and a way for a parent to check that application's status later. One school, Jnana Degula Academy, already runs on exactly this pattern — the examples below are the real endpoints and payloads its website uses.

Architecture

A school's website and CampusOS are two separate deployments that never share a codebase or a server — the website calls CampusOS the same way any browser would, over its public API.

Every request the website sends carries its own school_id — CampusOS never needs to be told which school a new website belongs to beyond that.

Seamless Login

The website's own login form collects a user ID and password and authenticates them for real — there is no separate "preview" login and no second sign-in step on CampusOS's side. On success, the browser is handed off to the CampusOS app already signed in.

No second login screen — the visitor only ever enters their password once, on the website's own page.

{
  "user_code": "jdaadm0001",
  "password": "••••••••",
  "school_id": "jnanadegulaacademy"
}

{
  "requires_2fa": false,
  "access_token": "…",
  "refresh_token": "…",
  "expires_in": 900,
  "user": {
    "id": "…",
    "role": "school_admin",
    "school_id": "jnanadegulaacademy",
    "first_name": "…",
    "…": "…"
  }
}

Redirect the browser to {CAMPUSOS_APP_URL}/session-adopt#at={access_token}&rt={refresh_token}&u={encodeURIComponent(JSON.stringify(user))} — a full navigation (window.location.href), not a client-side route change, since it's crossing to CampusOS's own origin.

Already has 2FA enabled — verify a code

{
  "pre_auth_token": "…",   // from the requires_2fa response
  "totp_code": "123456"
}

{
  "access_token": "…",
  "refresh_token": "…",
  "expires_in": 900,
  "user": { "…": "…" }
}

Same shape as a successful /auth/login — feed it straight into the same session-adopt redirect.

2FA mandated but not set up yet

{ "setup_token": "…" }  // from the requires_2fa_setup response

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code_url": "data:image/png;base64,…",
  "backup_codes": ["…", "…", "…"]
}

Render the QR code (an <img> pointed straight at qr_code_url — it's already a data URI, no extra fetch needed), show the backup codes once, then collect a 6-digit code to confirm:

{ "setup_token": "…", "totp_code": "123456" }

{
  "access_token": "…",
  "refresh_token": "…",
  "expires_in": 900,
  "user": { "…": "…" }
}

Same response shape again — same session-adopt redirect. Every path through login (plain, verify, or setup) ends at exactly one place.

Admission Enquiry

A school's own admission/"Apply Now" form can post directly to CampusOS — every submission becomes a real entry in that school's Admission Pipeline, not just an email.

{
  "school_id": "jnanadegulaacademy",
  "child_name": "Aditi Rao",
  "class_applying": "Class 3",
  "parent_name": "Suresh Rao",
  "parent_phone": "9845012345",
  "parent_email": "suresh.rao@example.com",
  "source": "website"
}

{
  "id": "…",
  "status": "new",
  "reference_no": "INQ/2025-26/0089"
}

Show the returned reference_no back to the parent — it's what they'll use later to check status (see next section). class_applying can be a plain text field, or — for a nicer form — read from GET /schools/:school_id/info's classes list, so the dropdown always matches whatever the school has actually configured, with no separate list to keep in sync by hand.

Application Status Check

Lets a parent check their own application's progress later, without a CampusOS login — reference number alone isn't accepted as proof of identity, since a parent shares theirs with no one else's information exposed by it.

{
  "school_id": "jnanadegulaacademy",
  "reference_no": "INQ/2025-26/0089",
  "parent_phone": "9845012345"
}

{
  "reference_no": "INQ/2025-26/0089",
  "child_name": "Aditi Rao",
  "class_applying": "Class 3",
  "status": "under_review",
  "status_label": "Under Review",
  "submitted_at": "2026-08-01T09:12:00Z",
  "stages": [ { "status": "new", "label": "Received" }, "…" ],
  "current_stage_index": 1
}

stages is the ordered, non-rejected path (new → under_review → interview_scheduled → selected → enrolled); current_stage_index is -1 when status is rejected, since that can happen from any stage — render it as its own outcome rather than a point on the progress bar.

General Contact Form

Setup Checklist for a New School's Website

1. Provision the school in CampusOS. Done once, by Stavion's Super Admin console — produces the school's school_id and its first Admin/Principal login.

2. Add the school's own constants to the website's codebase. Three values: the school_id, the CampusOS API base URL, and the CampusOS app URL (see Environments) — the only place this school's identity lives.

3. Build the login form. Posts to /auth/login with the website's own school_id; on success, redirects to /session-adopt (see Seamless Login).

4. Build the admission enquiry form. Posts to /admissions/inquiry; shows the returned reference number back to the parent.

5. Add a status-check form (optional but recommended). Posts to /admissions/track with the reference number and phone the parent submitted with.

6. Set up the school's own Resend account for general contact. Independent of CampusOS — see General Contact Form.

7. Add the small "Powered by Stavion" credit to the footer. One muted, low-emphasis line, linking to staviontech.com in a new tab — small enough to never compete with the school's own branding, present on every CampusOS-connected site so a visitor can always find who built it. The school's own name and logo stay the prominent identity everywhere else; this is the only Stavion mark on the public site.

   <a href="https://staviontech.com" target="_blank" rel="noopener noreferrer">
     Powered by Stavion
   </a>

Endpoint Reference

Environments

The same website codebase moves between environments by changing exactly these two values — nothing else about the integration changes.