Admin portal wiring

The staff onboarding portal lives at /admin/* in the frontend (src/app/admin/). It is a separate, cl_admin_session-gated surface from the tenant console — see Proxy and sessions for the cookie mechanics both share. Every call this portal makes goes through two files:

src/lib/api/adminAuth.ts — sign-in/sign-out and the CSRF-aware adminSend() mutation helper every /admin/* write uses.
src/lib/api/adminOnboarding.ts — every tenant-lifecycle operation: create, provision, ingest, train, activate, invite, go live.

All of it is TanStack Query on top of the proxy (apiGet/apiSend from src/lib/api/client.ts), so every table below names the query key or mutation the calling component uses, exactly as it appears in the source.

`adminAuth.ts`: every exported function

Function	Backend operation	Called from	What the UI does with the response
`adminLogin(email, password)`	`POST /admin/login`	`src/app/admin/login/page.tsx` form submit; also the “Causeloop Employee” tab of `src/app/login/page.tsx`	On success: `router.push("/admin")` + `router.refresh()`. On failure: maps `429` → “Too many attempts”, `401` → “Invalid email or password”, anything else → “Sign-in failed — is the app server running?”
`adminLogout()`	`POST /admin/logout`	`AdminLogoutButton` (`src/app/admin/(portal)/AdminLogoutButton.tsx`), rendered in `AdminRail`	Always (even on throw, via `finally`) `router.push("/admin/login")` + `router.refresh()`
`adminMe()`	`GET /admin/me`	No current call site. Exported but unused — the portal’s actual auth gate (`src/app/admin/(portal)/layout.tsx`) calls `${BACKEND_URL}/admin/me` directly with a manually attached cookie header instead, since it runs as a server component before any client-side query client exists.	—
`adminSend(method, path, body)`	(helper, not an endpoint)	Every mutation in `adminOnboarding.ts`	Reads `readCsrfToken()` (`src/lib/authCookies.ts`) and attaches it as `x-csrf-token` on every write; a `GET` never needs it

adminMe() being unused isn’t a bug in the wiring — the layout’s own direct-fetch approach exists because Next.js server components can’t use a browser-side useQuery hook, and the layout needs the identity check to happen before rendering anything (including redirecting to /admin/login). If a future client component needs to re-check identity after mount, adminMe() is the ready-made call for it.

Auth gate: `src/app/admin/(portal)/layout.tsx`

Every route under /admin/(portal) — the tenant directory, the wizard, tenant detail, control plane, jobs — is wrapped by this server component. It reads the cl_admin_session cookie, forwards it as a raw Cookie header to ${BACKEND_URL}/admin/me (bypassing the client-side proxy entirely, since it runs server-side), and redirects to /admin/login if the cookie is missing or the backend rejects it. On success it renders <AdminRail employee={employee}> with the resolved EmployeeIdentity (id, email, full_name, control_role).

Tenant directory — `src/app/admin/(portal)/page.tsx`

The landing page after sign-in: a KPI strip plus the full tenant list.

Call	Type	Key	Backend operation	UI effect
`listTenants()`	query	`["admin-tenants"]`	`GET /admin/tenants`	Renders KPI row (`Tenants`, `Live`, `Onboarding`, `Isolation model`) and the tenant list (name, slug/industry/region, model route + trained date, lifecycle chip)
`impersonateTenant(tenantId)`	mutation	—	`POST /admin/tenants/{tenant_id}/impersonate`	On success: `router.push("/")` + `router.refresh()` — see Impersonation redirect below. On error: shows the backend’s `detail` string (e.g. “Tenant has no active users to impersonate.”)

The Open portal → button that triggers impersonateTenant only renders when tenant.lifecycle_state === "live" — the backend independently enforces the same rule (409 Tenant is not live yet., see services/api/auth/tenant_auth.py), so this is a UX affordance, not the security boundary.

New client wizard — `src/app/admin/(portal)/tenants/new/page.tsx`

A six-step linear flow (Client → Environment → Data & PII → Sources → Model training → Activation) that walks a single tenant from creation to live. Every step after the first is gated on the previous step’s mutation having succeeded — the wizard holds tenantId in local state once step 0 resolves, and every subsequent call is scoped to that id.

Step	Call	Type	Key	Backend operation	UI effect
0. Client	`createTenant({slug, name, industry, region, primary_contact_email})`	mutation	—	`POST /admin/tenants`	On success: stores `tenant.id`, advances to step 1. On error: shows `err.detail`
1. Environment	`provisionTenant(tenantId)`	mutation	—	`POST /admin/tenants/{tenant_id}/provision`	Invalidates `["wz-provision-status", tenantId]` on success, which restarts the poll below
1. Environment	`getProvisionStatus(tenantId)`	query	`["wz-provision-status", tenantId]`	`GET /admin/tenants/{tenant_id}/provision/status`	See Provisioning poll
2. Data & PII	`uploadIngestFile(tenantId, file)`	mutation	—	`POST /admin/tenants/{tenant_id}/ingest/upload` (multipart)	See Upload flow
2. Data & PII	`commitIngest(tenantId, uploadId, mapping)`	mutation	—	`POST /admin/tenants/{tenant_id}/ingest/commit`	On success: clears `uploadResult`, sets `datasetCommitted = true`, unlocking `Continue →`
2. Data & PII	`putDataPolicy(tenantId, {residency, retention, pii_redaction})`	mutation	—	`PUT /admin/tenants/{tenant_id}/data-policy`	Fired once, on the step 2 → 3 transition (`handleNext`), not on every field change
—	`getDataPolicy(tenantId)`	—	—	`GET /admin/tenants/{tenant_id}/data-policy`	No current call site. Exported from `adminOnboarding.ts` and present in `product_app.py`’s `ONBOARDING_OPERATIONS` allowlist, but neither the wizard nor the tenant detail page reads it back — the wizard only ever writes the policy via `putDataPolicy` on the step 2 → 3 transition
3. Sources	`seedSources(tenantId, kinds)`	mutation	—	`POST /admin/tenants/{tenant_id}/sources/seed`	Fired on step 3 → 4 transition if at least one source kind is selected and sources aren’t already seeded
4. Model training	`putTrainingConfig(tenantId, {...})` then `trainModel(tenantId)`	mutation (single `mutationFn` awaits both calls in sequence)	—	`PUT /admin/tenants/{tenant_id}/training-config` then `POST /admin/tenants/{tenant_id}/train`	Invalidates `["wz-train-status", tenantId]` on success
4. Model training	`getTrainStatus(tenantId)`	query	`["wz-train-status", tenantId]`	`GET /admin/tenants/{tenant_id}/train/status`	See Training poll
4. Model training	`listCheckpoints(tenantId)`	query	`["wz-checkpoints", tenantId]`	`GET /admin/tenants/{tenant_id}/checkpoints`	Enabled only once `trained` is true; renders cluster count / noise % / silhouette from the newest checkpoint
5. Activation	`activateCheckpoint(tenantId, version, shareOutputs)` → `inviteUser(tenantId, adminEmail, "org_admin")` → `goLive(tenantId)`	three sequential `await`s inside a plain `finishGoLive()` function, not react-query mutations	—	`POST .../activate`, then `POST .../invite`, then `POST .../go-live`	On success: `router.push(/admin/tenants/${tenantId})`. On any failure: shows `err.detail`, the flow stops wherever it failed (partial completion is visible on the tenant detail page’s own step checklist)

The wizard’s role_profile_key for the initial admin invite is hardcoded to "org_admin" — the profile whose users.manage permission maps to the "Risk Admin" display role in the tenant console (mapPermissionsToWorkspaceRole in src/lib/api/tenantAuth.ts).

Tenant detail — `src/app/admin/(portal)/tenants/[tenantId]/page.tsx`

The same lifecycle as the wizard, but re-entrant: any step can be revisited for an existing tenant, driven entirely by what getTenant() and the checkpoint/invitation queries already show as done.

Section	Call	Type	Key	Backend operation	UI effect
(page-wide)	`getTenant(tenantId)`	query	`["admin-tenant", tenantId]`	`GET /admin/tenants/{tenant_id}`	Drives every `Step` component’s `done` flag; `refetchInterval` polls every 2s while `provisioning?.status === "running"`
1. Provision	`provisionTenant(tenantId)`	mutation	—	`POST /admin/tenants/{tenant_id}/provision`	Invalidates `["admin-tenant", tenantId]` and `["admin-tenant-provision-status", tenantId]`
1. Provision	`getProvisionStatus(tenantId)`	query	`["admin-tenant-provision-status", tenantId]`	`GET .../provision/status`	Enabled while `lifecycle_state` is `draft` or `provisioning`; polls every 2s while `running`
2. Ingest	`uploadIngestFile(tenantId, file)`	mutation	—	`POST .../ingest/upload` (multipart)	See Upload flow
2. Ingest	`commitIngest(tenantId, uploadId, mapping)`	mutation	—	`POST .../ingest/commit`	Invalidates `["admin-tenant", tenantId]` and `["admin-tenant-retrain-recommendation", tenantId]`
3. Training config	`putTrainingConfig(tenantId, {...})`	mutation	—	`PUT .../training-config`	Sets `configSaved = true`
4. Train	`trainModel(tenantId)`	mutation	—	`POST .../train`	Invalidates `["admin-tenant-train-status", tenantId]`
4. Train	`getTrainStatus(tenantId)`	query	`["admin-tenant-train-status", tenantId]`	`GET .../train/status`	Polls every 2s while `running`; a `useEffect` also invalidates the checkpoints query the moment `status === "succeeded"` (see below)
Drift banner	`getRetrainRecommendation(tenantId)`	query	`["admin-tenant-retrain-recommendation", tenantId]`	`GET .../retrain-recommendation`	Renders one of four `DRIFT_COPY` banners (`no_checkpoint` / `up_to_date` / `incremental` / `full_retrain`) comparing the active checkpoint’s dataset version/row count against the latest ingested dataset
5. Activation	`listCheckpoints(tenantId)`	query	`["admin-tenant-checkpoints", tenantId]`	`GET .../checkpoints`	Enabled once training succeeds, or immediately for any already-provisioned tenant (`checkpointsExists`)
5. Activation	`activateCheckpoint(tenantId, version, shareOutputs)`	mutation	—	`POST .../activate`	Invalidates `admin-tenant`, `admin-tenant-checkpoints`, and `admin-tenant-retrain-recommendation`
6. Invite users	`inviteUser(tenantId, email, roleProfileKey)`	mutation	—	`POST .../invite`	Clears the email field, invalidates `["admin-tenant-invitations", tenantId]`
6. Invite users	`listInvitations(tenantId)`	query	`["admin-tenant-invitations", tenantId]`	`GET .../invitations`	Renders each invite’s email, role, invite `status`, and email `delivery_status`
7. Go live	`goLive(tenantId)`	mutation	—	`POST .../go-live`	Invalidates `["admin-tenant", tenantId]`; error surfaces inline

The checkpoints-query invalidation on training success is worth calling out because it isn’t the mutation’s own onSuccess doing it — training runs as an asynchronous background job (see Workers and jobs), so the moment that matters is the poll discovering succeeded, not the moment the POST /train call returns (which only means the job was queued):

useEffect(() => {
  if (trainStatusQuery.data?.status === "succeeded") {
    void queryClient.invalidateQueries({ queryKey: ["admin-tenant-checkpoints", tenantId] });
  }
}, [trainStatusQuery.data?.status, tenantId, queryClient]);

Without this effect, a checkpoints list fetched (empty) before training finished would never be told to refetch once the job actually completes, and the Activation step would never appear.

Control plane — `src/app/admin/(portal)/control-plane/page.tsx`

A read-only, cross-tenant infrastructure view.

Call	Type	Key	Backend operation	UI effect
`listTenants()`	query	`["admin-tenants"]`	`GET /admin/tenants`	Aggregated client-side into a lifecycle-state histogram and a `tenant_<slug>` schema list (tenants in the `offboarded` state are excluded from the schema list, since `scripts/offboard_tenant.py` drops the actual schema)
`fetchMetrics()`	query	`["admin-metrics"]`	`GET /metrics`	Parsed with `toJobDashboardData()`; only `queueDepth` is used on this page

Jobs — `src/app/admin/(portal)/jobs/page.tsx`

The operational dashboard, refreshing every 5 seconds.

Call	Type	Key	Backend operation	UI effect
`fetchMetrics()`	query	`["admin-metrics"]`, `refetchInterval: 5000`	`GET /metrics` (Prometheus text exposition, not JSON)	Parsed by `parsePrometheusText()` then reshaped by `toJobDashboardData()` into: pipeline queue depth, platform jobs by type/status, per-tenant ingest jobs by status, and LLM tokens used this month per tenant

GET /metrics is the one product-API operation the JSON client layer can’t parse as JSON — fetchMetrics() in src/lib/api/adminMetrics.ts reads the body as text and parses metric_name{labels} value lines itself rather than going through apiGet(). (GET /remediation/export.xlsx is the other non-JSON response in the product allowlist — see Tenant console wiring — but it returns a binary XLSX stream rather than Prometheus text, and it isn’t parsed by this metrics code path.) services/api/metrics_api.py defines more metric families (including causeloop_tenants_total and causeloop_platform_job_duration_seconds_avg) than toJobDashboardData() actually consumes: the frontend reshapes only causeloop_pipeline_queue_depth, causeloop_platform_jobs_total, causeloop_ingest_jobs_total, and causeloop_llm_tokens_used_this_month into the job dashboard’s queue depth, platform jobs, ingest jobs, and token-usage sections.

Provisioning and training polls

Both the wizard and the tenant detail page poll the same shape of job-status resource (JobStatus in adminOnboarding.ts) for two different jobs — provision_tenant and train_tenant_model (see Workers and jobs for how these are durably queued):

export interface JobStatus {
  status: "not_started" | "queued" | "running" | "succeeded" | "failed" | "cancelled";
  progress: number;
  error_detail: string | null;
  steps_completed?: string[];
}

The wizard’s own two refetchInterval callbacks (src/app/admin/(portal)/tenants/new/page.tsx) poll on "running" and "not_started" — not just "running" — at different intervals for the two jobs: 1200ms for provisioning, 1500ms for training.

// provision poll
refetchInterval: (q) =>
  q.state.data?.status === "running" || q.state.data?.status === "not_started" ? 1200 : false,
// train poll
refetchInterval: (q) =>
  q.state.data?.status === "running" || q.state.data?.status === "not_started" ? 1500 : false,

The comment in the wizard source explains why both poll on "not_started": provisioning starts on a background thread, so a poll that lands before the job’s first database write sees "not_started" — without also polling on that status, the query would permanently stop polling before the job ever transitions to "running". The tenant detail page’s own polls (POLL_INTERVAL_MS = 2000 in src/app/admin/(portal)/tenants/[tenantId]/page.tsx) are simpler: they poll every 2 seconds only while "running", never on "not_started". steps_completed (only populated for the provisioning job) drives the wizard’s own step-by-step checklist (create_schema, run_tenant_migrations, grant_app_rw, seed_role_profiles, create_storage_prefix, activate_onboarding) — the tenant detail page’s numbered Step sections are driven by getTenant()’s lifecycle/audit fields instead, not by steps_completed.

Upload flow (FormData)

Both uploadIngestFile() (staff-side historical dataset ingest) and its tenant-console counterpart uploadTenantSource() (covered in Tenant console wiring) follow the same shape: build a FormData, attach the CSRF header manually, and skip the JSON API client entirely because the body is multipart, not JSON.

export async function uploadIngestFile(tenantId: string, file: File): Promise<IngestUploadResult> {
  const csrf = readCsrfToken();
  const form = new FormData();
  form.append("file", file);
  const response = await fetch(`/api/backend/admin/tenants/${tenantId}/ingest/upload`, {
    method: "POST",
    headers: csrf ? { "x-csrf-token": csrf } : {},
    body: form,
  });
  if (!response.ok) {
    const body = await response.json().catch(() => ({ detail: response.statusText }));
    throw new Error(typeof body.detail === "string" ? body.detail : "Upload failed");
  }
  return (await response.json()) as IngestUploadResult;
}

Note what’s deliberately absent: no Content-Type header. Setting one manually on a FormData body would omit the multipart boundary the browser computes automatically — fetch sets the correct multipart/form-data; boundary=... header itself only when Content-Type is left unset. The response (IngestUploadResult) carries a preview, not a commit: upload_id, detected columns, a row_count, a 5-row preview, a suggested_mapping (column → canonical field), and detected_pii_columns (column → redaction strategy, matched by column-name heuristics on the backend). The wizard and tenant detail page both render the suggested mapping and PII warnings, then require a second, explicit commitIngest(tenantId, uploadId, mapping) call before the upload becomes a real dataset version — this two-step upload-then-commit split is what lets the operator review/correct the column mapping and see PII flags before anything lands in the tenant’s dataset.

Impersonation redirect

impersonateTenant(tenantId) is the one call in this portal that hands control to a different session type entirely: Two properties are worth being explicit about, both verified in services/api/auth/tenant_auth.py:

Which user gets impersonated is not a choice — the backend always selects the tenant’s earliest-created active TenantUser, so a staff member can never target a specific individual through this call; it’s always “become the first real user this tenant has.”
The audit log write is unconditional, not best-effort — the ControlAuditLog row (actor_type="employee", action="employee_impersonation", resource_id=<impersonated user id>) is written immediately after the session is minted, in a separate control-plane transaction (with control_uow(), after the with tenant_uow(tenant) block that mints the session has already committed). The two writes are not atomic with each other — a crash between the two commits would leave a minted session with no audit row — but every code path that successfully mints an impersonation session unconditionally proceeds to the audit write.

A staff member is only ever one router.refresh() away from the tenant console because the new cl_tenant_session cookie was set by the backend’s response and forwarded verbatim by the proxy (see Proxy and sessions) — the frontend never mints or copies a session token itself.

Using the API

Frontend Integration

Endpoints

Legacy Surfaces

Admin portal wiring

`adminAuth.ts`: every exported function

Auth gate: `src/app/admin/(portal)/layout.tsx`

Tenant directory — `src/app/admin/(portal)/page.tsx`

New client wizard — `src/app/admin/(portal)/tenants/new/page.tsx`

Tenant detail — `src/app/admin/(portal)/tenants/[tenantId]/page.tsx`

Control plane — `src/app/admin/(portal)/control-plane/page.tsx`

Jobs — `src/app/admin/(portal)/jobs/page.tsx`

Provisioning and training polls

Upload flow (FormData)

Impersonation redirect

​adminAuth.ts: every exported function

​Auth gate: src/app/admin/(portal)/layout.tsx

​Tenant directory — src/app/admin/(portal)/page.tsx

​New client wizard — src/app/admin/(portal)/tenants/new/page.tsx

​Tenant detail — src/app/admin/(portal)/tenants/[tenantId]/page.tsx

​Control plane — src/app/admin/(portal)/control-plane/page.tsx

​Jobs — src/app/admin/(portal)/jobs/page.tsx

​Provisioning and training polls

​Upload flow (FormData)

​Impersonation redirect

​Related

`adminAuth.ts`: every exported function

Auth gate: `src/app/admin/(portal)/layout.tsx`

Tenant directory — `src/app/admin/(portal)/page.tsx`

New client wizard — `src/app/admin/(portal)/tenants/new/page.tsx`

Tenant detail — `src/app/admin/(portal)/tenants/[tenantId]/page.tsx`

Control plane — `src/app/admin/(portal)/control-plane/page.tsx`

Jobs — `src/app/admin/(portal)/jobs/page.tsx`

Provisioning and training polls

Upload flow (FormData)

Impersonation redirect

Related